Get goal

GET /api/v3/goals/{id}

Request

Response

URL

GET https://example.aha.io/api/v3/goals/123

cURL command

curl --request GET 'https://example.aha.io/api/v3/goals/123' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Accept: application/json'

Request conventions

API key or OAuth2 access token. See Authentication.

Use your account domain and token in copied requests. Request values and conditional fields must satisfy your account’s validation rules.

URL settings

Account subdomain

The part before .aha.io. Leave blank to use the example domain.

ID or reference number of the goal

Response fields

Choose which fields to include in the response. Expand a field for examples and associated fields. Collections can only be returned on the top-level resource, not inside an associated resource.

Default response fields are returned until you select specific fields.

Search fields

Field	Type	Returned by default
Unique record ID.	integer	Yes
Include id in response
URL to view the record in Aha!	string	Yes
Include html_url in response
API URL for the record.	string	Yes
Include url in response
Name of the record.	string	Yes
Include name in response
Reference number of the record.	string	Yes
Include reference_num in response
Date and time when the record was created.	date-time	No
Include created_at in response
Date and time when the record was last updated.	date-time	No
Include updated_at in response
Position of the record relative to its siblings.	integer	No
Include position in response
Color assigned to the record as a hex value.	string	No
Include color in response
Estimated effort, from 0 to 100.	integer	No
Include effort in response
Estimated value, from 0 to 100.	integer	No
Include value in response
Progress completed for the record.	number	No
Include progress in response
Method used to calculate goal progress.	string	No
Include progress_source in response Allowed values: `manualfrom_featuresfrom_features_with_dependentsfrom_releasesfrom_releases_with_dependentsfrom_initiativesfrom_initiatives_with_dependentsfrom_descendantsfrom_descendants_with_dependentsfrom_features_completedfrom_features_completed_with_dependentsfrom_epicsfrom_epics_with_dependentsfrom_key_resultsfrom_key_results_with_dependents`
Name of the goal's success metric.	string	No
Include success_metric_name in response
HTML description of the goal's success metric.	string	No
Include success_metric_description in response
Status assigned to the record.	Status	No
Include status in response Expand this association to browse its response fields.
HTML description of the record.	Note	No
Include description in response Expand this association to browse its response fields.
Time frame assigned to the record.	TimeFrame	No
Include time_frame in response Expand this association to browse its response fields.
Workspace that contains the record.	Project	No
Include project in response Expand this association to browse its response fields.
Features associated with the goal. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=features[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include features in response Expand this association to browse its response fields.
Epics associated with the goal. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=epics[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include epics in response Expand this association to browse its response fields.
Initiatives associated with the goal. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=initiatives[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include initiatives in response Expand this association to browse its response fields.
Parent goals that this goal rolls up to. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=rollup_goals[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include rollup_goals in response Expand this association to browse its response fields.
Child goals that roll up to this goal. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=children[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include children in response Expand this association to browse its response fields.
Key results belonging to the goal. Only available when key results are enabled for the account. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=key_results[default]). Capped at 25 records. Only available on the top-level resource. Availability depends on account settings.	Collection	No
Collection envelope Records use the associated fields below. Type: `object` Required properties: records, has_more. url Type: `string` (uri) has_more Type: `boolean` next_url Type: `string` (uri) Include key_results in response Expand this association to browse its response fields.
Custom field values. Property names are custom field definition keys, and each value is one of the supported formats below, depending on the field type. Omitted unless requested with the fields parameter or submitted in the request. Fields with no stored value are omitted.	object	No
Include custom_fields in responseCustom field API key Custom field keys depend on your account. Request `fields=custom_fields` or `fields=custom_fields.your_key`.

Search matches the start of a field path and includes matching associations’ subfields. Use a dotted path to search within a specific association.

Response field selection

Return selected fields with a comma-separated fields parameter, or add a field to the defaults with fields=default,{field}. Expand an association above for its supported subfields and selection examples.

See field selection for details.

Response statuses

Error shape for 401, 403, 404

Type: object

error

Type: object

Required properties: status, code, message, request_id.

status

Type: integer

code

Type: string

message

Type: string

request_id

Type: string

Response envelope and pagination

record: a single record. Fields are documented above.

Download the complete OpenAPI specification