List metrics

Returns saved metrics in the project. Results are paginated with cursor-based
pagination. Full metric definitions are included in list responses.

Sortable fields are updated_at and name; prefix with - for descending.
Defaults to -updated_at (most recently updated first).

get/v1/projects/{project_id}/metrics

Authorizations

Authorizationstringrequired

http

Path parameters

project_idstringrequired

Amplitude project identifier, backed by the canonical app ID.

Example:12345

Constraints:pattern: ^[0-9]+$

Query parameters

cursorstring

Opaque cursor from pagination.next_cursor on the previous response. Numeric offsets are capped by the underlying search index (10,000 results per query). Well-formed pagination stops before that window; requests whose cursor would exceed it return 400 pagination_not_supported.

Constraints:nullable

limitinteger

Number of items to return. Defaults to 50, max 200.

Default:50

Constraints:min: 1max: 200

qstring

Full-text search query.

metric_typestring

Filter list results to a specific metric type.

Allowed values:uniquestotalsformulaprop_sumprop_avgretentionconversionunknown

sortstring

Sort field. Prefix with - for descending. Supported values are updated_at and name.

Example:-updated_at

Response

application/json

200· Successful response.

dataobject[]required

Show child attributes

idstringrequired

Stable metric identifier.

objectstringrequired

Resource-type discriminator. Always metric.

project_idstringrequired

Constraints:pattern: ^[0-9]+$

namestringrequired

descriptionstring

Constraints:nullable

metric_typestringrequired

Public metric type discriminator (snake_case). See the enum for supported values.Unsupported or unrecognized metric types are surfaced as unknown. Clients should treat unknown as "a metric type this API version does not model yet".

Allowed values:uniquestotalsformulaprop_sumprop_avgretentionconversionunknown

definitiononeOfrequired

Type-specific metric definition. The metric_type discriminator selects the required fields. Aligns with MCP shared-schema capabilities.

Constraints:objectobjectobjectobjectobjectobjectobjectobject

metric_typestringrequired

eventobject

event_typestringrequired

Event name (e.g. Page View, _active).

filtersobject[]

Default:[]

property_keystringrequired

Property key to filter on.

operatorstringrequired

Filter operator (matches Amplitude property operators).

valuesstring[]

Values to match against.

Default:[]

property_typestring

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

group_typestring

Group type for group properties. Empty string for non-group.

Default:

group_byobject[]

Properties to group by. Required for formula metrics that use property aggregation functions like PROPSUM(A) or PROPAVG(A).

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Property name to group by.

group_typestring

Group type for group properties. Empty string for non-group.

Default:

count_groupstring

What to count. User for unique users, Event for event totals.

Default:User

eventsobject[]

Event definitions referenced by letter (A, B, C...) in the formula string.

event_typestringrequired

Event name (e.g. Page View, _active).

filtersobject[]

Default:[]

property_keystringrequired

Property key to filter on.

operatorstringrequired

Filter operator (matches Amplitude property operators).

valuesstring[]

Values to match against.

Default:[]

property_typestring

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

group_typestring

Group type for group properties. Empty string for non-group.

Default:

group_byobject[]

Properties to group by. Required for formula metrics that use property aggregation functions like PROPSUM(A) or PROPAVG(A).

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Property name to group by.

group_typestring

Group type for group properties. Empty string for non-group.

Default:

formulastring

Formula string. Reference events by letter. Functions include UNIQUES(A), TOTALS(A), PROPSUM(A), PROPAVG(A), PROPMIN(A), PROPMAX(A), PROPCOUNT(A), PROPCOUNTAVG(A), REVENUETOTAL(A).

aggregation_propertyobject

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Numeric property name to aggregate.

group_typestring

Default:

start_eventobject

event_typestringrequired

Event name (e.g. Page View, _active).

filtersobject[]

Default:[]

property_keystringrequired

Property key to filter on.

operatorstringrequired

Filter operator (matches Amplitude property operators).

valuesstring[]

Values to match against.

Default:[]

property_typestring

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

group_typestring

Group type for group properties. Empty string for non-group.

Default:

group_byobject[]

Properties to group by. Required for formula metrics that use property aggregation functions like PROPSUM(A) or PROPAVG(A).

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Property name to group by.

group_typestring

Group type for group properties. Empty string for non-group.

Default:

return_eventobject

event_typestringrequired

Event name (e.g. Page View, _active).

filtersobject[]

Default:[]

property_keystringrequired

Property key to filter on.

operatorstringrequired

Filter operator (matches Amplitude property operators).

valuesstring[]

Values to match against.

Default:[]

property_typestring

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

group_typestring

Group type for group properties. Empty string for non-group.

Default:

group_byobject[]

Properties to group by. Required for formula metrics that use property aggregation functions like PROPSUM(A) or PROPAVG(A).

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Property name to group by.

group_typestring

Group type for group properties. Empty string for non-group.

Default:

return_oninteger

Number of intervals to return on.

Constraints:min: 1max: 30

return_on_intervalinteger

Interval length in days. 1 for daily, 7 for weekly, 30 for monthly.

Constraints:min: 1max: 30

funnel_eventsobject[]

Ordered funnel steps (minimum 2 events).

event_typestringrequired

Event name (e.g. Page View, _active).

filtersobject[]

Default:[]

property_keystringrequired

Property key to filter on.

operatorstringrequired

Filter operator (matches Amplitude property operators).

valuesstring[]

Values to match against.

Default:[]

property_typestring

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

group_typestring

Group type for group properties. Empty string for non-group.

Default:

group_byobject[]

Properties to group by. Required for formula metrics that use property aggregation functions like PROPSUM(A) or PROPAVG(A).

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Property name to group by.

group_typestring

Group type for group properties. Empty string for non-group.

Default:

funnel_modestring

Allowed values:orderedunorderedsequential

conversion_secondsinteger

Maximum time window to complete the funnel, in seconds (e.g. 86400 = 1 day, 604800 = 7 days).

Constraints:min: 1

funnel_paths_to_collectstring

Whether the funnel measures unique users completing the path or total conversion path counts.

Allowed values:uniquestotals

funnel_constant_propertiesobject[]

Properties held constant across funnel steps.

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Numeric property name to aggregate.

group_typestring

Default:

funnel_compute_propertyobject

property_typestringrequired

Property namespace for filters, group-bys, and aggregations.

Allowed values:eventusergroup

valuestringrequired

Numeric property name to aggregate.

group_typestring

Default:

funnel_compute_property_functionstring

Allowed values:sumavg

versionintegerrequired

Optimistic concurrency version. Required on PATCH; incremented on each successful update.

Constraints:min: 1

created_atstringrequired

Constraints:format: date-timenullable

updated_atstringrequired

Constraints:format: date-timenullable

created_bystring

Creator email or login identifier when available.

Constraints:nullable

urlstringrequired

Deep link to the metric in the Amplitude UI.

Constraints:format: uri

archivedbooleanrequired

Whether the metric is archived (soft-deleted).

is_officialboolean

Whether the metric is marked official.

is_restrictedboolean

Whether the metric is restricted.

key_propertiesobject[]

Key properties associated with the metric definition.

property_typestringrequired

valuestringrequired

group_typestring

paginationobjectrequired

Show child attributes

next_cursorstringrequired

Cursor for the next page, or null on the last page. Chart list responses may stop before all project charts are enumerated because the search backend caps each query at 10,000 sorted hits.

Constraints:nullable

has_morebooleanrequired

List metrics

curl -X GET "https://developer-api.amplitude.com/v1/projects/12345/metrics?limit=50&sort=-updated_at" \
  -H "Content-Type: application/json" \
  -H "Authorization: YOUR_API_KEY"

Was this helpful?