List epics

GET /api/v3/epics

Request

Response

URL

GET https://example.aha.io/api/v3/epics

cURL command

curl --request GET 'https://example.aha.io/api/v3/epics' \
  --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.

per_page

Number of records per page (default 25, max 200)

after

Opaque cursor from a previous response to fetch the next page

Fields

Choose fields to return, filter, or sort. 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.

Add and edit filters and sorting in field details. Examples illustrate the response shape, not matching records.

Search fields

Field	Type	Returned by default	Sortable	Supported filters
Unique record ID.	integer	Yes	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include id in responseSort by id
URL to view the record in Aha!	string	Yes	No	None
Include html_url in response
API URL for the record.	string	Yes	No	None
Include url in response
Name of the record.	string	Yes	Yes	`eqnot_eqcontainsstarts_withinnot_inemptynot_empty`
Include name in responseSort by name
Reference number of the record.	string	Yes	Yes	`eqnot_eqcontainsstarts_withinnot_inemptynot_empty`
Include reference_num in responseSort by reference_num
Date and time when the record was created.	date-time	No	Yes	`eqgtgteltltebetweenemptynot_empty`
Include created_at in responseSort by created_at
Date and time when the record was last updated.	date-time	No	Yes	`eqgtgteltltebetweenemptynot_empty`
Include updated_at in responseSort by updated_at
Start date of the record.	date	No	Yes	`eqgtgteltltebetweenemptynot_empty`
Include start_date in responseSort by start_date
End date of the record.	date	No	Yes	`eqgtgteltltebetweenemptynot_empty`
Include end_date in responseSort by end_date
Progress completed for the record.	number	No	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include progress in responseSort by progress
Score assigned to the record.	number	No	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include score in responseSort by score
Initial work estimate for the record.	number	No	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include initial_estimate in responseSort by initial_estimate
Detailed work estimate for the record.	number	No	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include detailed_estimate in responseSort by detailed_estimate
Remaining work estimate for the record.	number	No	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include remaining_estimate in responseSort by remaining_estimate
Work completed for the record.	number	No	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include work_done in responseSort by work_done
Position of the record relative to its siblings.	integer	No	Yes	`eqnot_eqgtgteltlteinnot_inbetweenemptynot_empty`
Include position in responseSort by position
How progress is calculated for the record.	string	No	No	`eqnot_eqinnot_inemptynot_empty`
Include progress_source in response Allowed values: `manualfrom_featuresfrom_features_with_dependentsfrom_remaining_estimatefrom_remaining_estimate_with_dependentsfrom_todosfrom_todos_with_dependentsfrom_features_completedfrom_features_completed_with_dependents`
How start and end dates are calculated for the record.	string	No	No	None
Include duration_source in response Allowed values: `manualfrom_featuresfrom_releases`
Whether estimates are entered on the record or calculated from its features.	string	No	Yes	`eqnot_eqinnot_inemptynot_empty`
Include estimate_source in responseSort by estimate_source Allowed values: `manualfrom_features`
Status assigned to the record.	Status	No	No	`emptynot_empty`
Include status in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
User assigned to the record.	AssignedToUser	No	No	`emptynot_empty`
Include assigned_to_user in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
User who created the record.	User	No	No	`emptynot_empty`
Include created_by_user in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
HTML description of the record.	Note	No	No	`emptynot_empty`
Include description in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Workspace that contains the record.	Project	No	No	`emptynot_empty`
Include project in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Release associated with the record.	Release	No	No	`emptynot_empty`
Include release in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Release phase associated with the record.	ReleasePhase	No	No	`emptynot_empty`
Include release_phase in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Iteration associated with the record.	Iteration	No	No	`emptynot_empty`
Include iteration in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Initiative associated with the record.	Initiative	No	No	`emptynot_empty`
Include initiative in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Team assigned to the record. Availability depends on account settings.	Project	No	No	`emptynot_empty`
Include team in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Team status assigned to the record. Availability depends on account settings.	Status	No	No	`emptynot_empty`
Include team_status in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Program increment associated with the record.	ProgramIncrement	No	No	`emptynot_empty`
Include program_increment in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Time code assigned to the record. Only available when timesheets are enabled for the account. Availability depends on account settings.	TimeCode	No	No	`emptynot_empty`
Include time_code in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Tags associated with the epic. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=tags[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No	No	`emptynot_empty`
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 tags in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Features associated with the epic. 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	No	`emptynot_empty`
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 Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Goals associated with the epic. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=goals[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No	No	`emptynot_empty`
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 goals in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Key results associated with the epic. 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	No	`emptynot_empty`
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 Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
Individual metric values for the epic's scorecards. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=score_facts[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No	No	`emptynot_empty`
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 score_facts in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.
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	No	By custom field type
Include custom_fields in responseCustom field API keyCustom field type Custom field keys depend on your account. Request `fields=custom_fields` or `fields=custom_fields.your_key`. Filter with `filter.{operator}[custom_fields.your_key]=value`. Supported custom field types: text: eq, not_eq, contains, starts_with, in, not_in, empty, not_empty url: eq, not_eq, contains, starts_with, in, not_in, empty, not_empty number: eq, not_eq, gt, gte, lt, lte, in, not_in, between, empty, not_empty date: eq, gt, gte, lt, lte, between, empty, not_empty checkbox: eq Other custom field types cannot be filtered. Custom fields cannot be sorted.
Users watching the record for update notifications. Omitted by default. Request the field for inline records with default sub-fields, or choose sub-fields (e.g., ?fields=watchers[default]). Capped at 25 records. Only available on the top-level resource.	Collection	No	No	`emptynot_empty`
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 watchers in response Association filters apply to this field itself. Expand its subfields below to see their individual capabilities.

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

Query syntax

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.

Filter with filter.{operator}[{field}]=value. Multiple filters combine with AND. Use comma-separated values for in and not_in, two inclusive bounds for between, and true for empty and not_empty.

Sort with sort.asc={field} or sort.desc={field}. Explicit sorting limits results to 1,000 records. Omit sorting to retrieve all results in descending ID order.

Set the page size with per_page. Follow pagination.next_url while pagination.has_more is true.

Filter operators

eq equals; not_eq does not equal; contains contains text; starts_with starts with text (both case-insensitive).

gt greater than; gte greater than or equal; lt less than; lte less than or equal.

in matches any listed value; not_in excludes listed values; between matches an inclusive range; empty and not_empty check for an absent or present value.

See field selection, filtering, and pagination and sorting limits for details.

Response statuses

Error shape for 400, 401, 403

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

records: array of records. Fields are documented above.

pagination

Type: object

Required properties: has_more.

has_more

Type: boolean

next_cursor

Type: string or null

next_url

Type: string or null (uri)

truncated

Type: boolean

truncated_message

Type: string

Download the complete OpenAPI specification