Dashboard REST API

Considerations

URL encode special characters in event types, event properties, and user property names. For example, encode Play Song as Play%20Song. Refer to the W3Schools encoding reference.
Some examples use backslash syntax to escape characters in cURL. If you aren't using cURL, don't encode your request with backslash escape characters.
The Dashboard REST API time zone matches your Amplitude project's time zone.

Rate limits

Each endpoint has a concurrent limit and a rate limit. The concurrent limit restricts the number of requests you can run at the same time. The rate limit restricts the total number of queries per hour. Exceeding these limits returns a 429 error. Limits are per project, and the 429 error includes information about which limit you exceeded.

Concurrent Limit: Run up to 5 concurrent requests across all Amplitude REST API endpoints, including cohort download.

User activity and user search limits

The User Activity and User Search endpoints have different limits:

Concurrent Limit: Run up to 10 concurrent requests for these endpoints.
Rate Limit: Run up to 360 queries per hour for these endpoints.

Endpoint costs

Endpoints use a cost per query rate limit model. Cost doesn't refer to a monetary value. Cost refers to rate limits and API usage limits. This method provides equal API availability for all queries. Amplitude calculates rate costs with this formula:

cost = (# of days) * (# of conditions) * (cost for the query type)

Amplitude determines each variable as follows:

Number of days: The number of days in the query.
Number of conditions: The number of segments plus the number of conditions within the segments applied to the chart. Each group by counts as 4 segments.

Segments and conditions

Segments are comparison groups. For more information, refer to Add user segments.
Conditions represent top-level filters. Cohorts, WHERE, and "who performed/did" are conditions in Amplitude. Event filters don't count as conditions for API costs.

Different chart types have different costs. For endpoints not listed here, the cost is 1. The limits for these endpoints, measured in cost per query, are:

Concurrent Limit: Up to 1000 cost within a five minute period.
Rate Limit: Up to 108,000 cost per hour.
Event Segmentation: Equal to the number of events in the left module. If any event has a group by, add a cost of 4 per group by and event.
Funnel Analysis: The number of events in the funnel multiplied by two. If any event has a group by, add a cost of 4 per group by and event.
Retention Analysis: The cost for this chart is 8.
User Sessions: The cost for this chart is 4.

Shared query parameters

These query parameters are shared across several Dashboard REST API endpoints.

For built-in Amplitude properties, valid values are version, country, city, region, DMA, language, platform, os, device, device_type, start_version, and paying.
For custom user properties, format the key as gp:name.

Parameter	Description
`e`	A full event with optional property filters or group by. Events are represented as JSON objects as described in event format.
`s`	Segment definitions. Include as many as needed. Segments are represented as JSON arrays, where each element is a JSON object corresponding to a filter condition as described segment definition.
`g`	The property to group by, for example `platform`. Available only when there is a single segment. Limit: two.

Event format

The event parameter accepts these keys:

Key	Required	Description
`event_type`	Yes	The event type. For custom events, prefix the name with `ce:` (for example, `ce:name`). For '[Amplitude] Any Active Event', use `_active`. For '[Amplitude] Any Event', use `_all`. For '[Amplitude] Revenue', use `revenue_amount`. For '[Amplitude] Revenue (Verified)', use `verified_revenue`. For '[Amplitude] Revenue (Unverified)', use `unverified_revenue`.
`filters`	No	A list of property filters. Each filter is a JSON object. Refer to Filter object keys.
`group_by`	No	A list of properties to group by (at most 2). Each group by is a JSON object with `type` (either `event` or `user`) and `value` (the property name).

Filter object keys

Key	Required	Description
`subprop_type`	Yes	Either `event` or `user`, indicating an event or user property.
`subprop_key`	Yes	The name of the property to filter on. For non-Amplitude custom user properties, prepend the user property name with `gp:`. The `gp:` prefix isn't needed for event properties.
`subprop_op`	Yes	The filter operator. One of `is`, `is not`, `contains`, `does not contain`, `less`, `less or equal`, `greater`, `greater or equal`, `set is`, or `set is not`.
`subprop_value`	Yes	A list of values to filter the event property by.

Event format example

json

{
  "event_type": "CompletedProfile",
  "filters": [
    {
      "subprop_type": "event",
      "subprop_key": "EmailVerified",
      "subprop_op": "is",
      "subprop_value": [
        "true"
      ]
    },
    {
      "subprop_type": "user",
      "subprop_key": "gp:SignUpDate",
      "subprop_op": "is",
      "subprop_value": [
        "2021-08-18"
      ]
    }
  ],
  "group_by": [
    {
      "type": "user",
      "value": "platform"
    }
  ]
}

Segment definition

Segments filter users based on their properties or behaviors. Each segment is a JSON object.

Key	Required	Description
`prop`	Yes	The name of the property to filter on. For behavioral cohorts, the property name is `userdata_cohort`. Example: `s=\[\{"prop":"userdata_cohort","op":"is","values":\["XYXxxzz"\]\}\]`, where `XYXxxzz` is the identifier from the Behavioral Cohort's URL (`https://analytics.amplitude.com/org_name/cohort/XYXxxzz`).
`op`	Yes	The filter operator. One of `is`, `is not`, `contains`, `does not contain`, `less`, `less or equal`, `greater`, `greater or equal`, `set is`, or `set is not`.
`values`	Yes	A list of strings to filter the segment by. When segmenting by a cohort, the value is the cohort ID, found in the cohort's URL in the web app (for example, `5mjbq8w`).
`type`	No	Set to `"event"` when using a "who performed" filter to segment users based on event performance.
`event_type`	No	The event to filter on when using a "who performed" filter. Required when `type` is `"event"`.
`filters`	No	Event property filters when using a "who performed" filter. An array of filter objects.
`value`	No	The count threshold for the "who performed" filter. Use with `time_type` and `time_value`.
`time_type`	No	Time window type for the "who performed" filter. One of `"forEachInterval"`, `"currentInterval"`, or `"allTime"`.
`time_value`	No	Number of days for the time window when `time_type` equals `"forEachInterval"`.

Segment definition examples

User property filter

Filter users by property values.

json

[
    {
        "prop": "version",
        "op": "contains",
        "values": ["1.0", "2.0"]
    },
    {
        "prop": "gp:gender",
        "op": "is",
        "values": ["female"]
    }
]

"Who performed" filter

Filter users who performed a specific event. This example filters users who performed the signup - end signup event at least once in the last 30 days.

json

[
    {
        "op": ">=",
        "type": "event",
        "event_type": "signup - end signup",
        "filters": [],
        "value": 0,
        "time_type": "forEachInterval",
        "time_value": 30
    }
]

You can combine multiple filters. This example filters users in the United States who performed the signup - end signup event at least once.

json

[
    {
        "prop": "country",
        "op": "is",
        "values": ["United States"]
    },
    {
        "op": ">=",
        "type": "event",
        "event_type": "signup - end signup",
        "filters": [],
        "value": 1,
        "time_type": "allTime"
    }
]

Export data tables

You can use the Dashboard REST API to export data from data tables. Query any Data Table chart type, and don't include start or end dates in the query.

Get results from an existing chart

Get JSON results from any saved chart by chart ID. GET https://amplitude.com/api/3/chart/chart_id/csv

bash

curl --location --request GET 'https://amplitude.com/api/3/chart/:chart_id/csv' \
-u '{api_key}:{secret_key}'

Path variables

Name	Description
`chart_id`	Required. The chart's ID. Get the chart ID from the chart's URL in the web app. For example, `abc123` in this URL: `https://analytics.amplitude.com/demo/chart/abc123`.

Response

Responses vary based on the chart's type.

Get active and new user counts

Get the number of active or new users.

GET https://amplitude.com/api/2/users

bash

curl --location --request GET 'https://amplitude.com/api/2/users?start=STARTDATE&end=ENDDATE' \
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221001`.
`m`	Optional. Either `new` or `active` to get the count you need. Defaults to `active`.
`i`	Optional. Either 1, 7, or 30 for daily, weekly, and monthly counts, respectively. Defaults to 1.
`s`	Optional. Segment definitions. Defaults to none. Defined in Shared query parameters.
`g`	Optional. The property to group by. Defaults to none. Defined in Shared query parameters.

Response

The response is a JSON object with this schema:

Attribute	Description
`series`	An array with one element for each group, in the same order as `seriesMeta`. Each element is an array containing the metric value for each day in `xValues`.
`seriesMeta`	An array of labels, one for each segment.
`xValues`	An array of date strings in `YYYY-MM-DD` format, one for each date in the specified range.

json

{
    "data": {
        "series": [ 
            [46109, 47542],
            [42845, 42626]
        ],
        "seriesMeta": ["United States", "Canada"],
        "xValues": ["2017-08-14", "2017-08-15"]
    }
}

Get session length distribution

Get the number of sessions for each predefined length (bucket) period during a specified date range.

GET https://amplitude.com/api/2/sessions/length

bash

curl --location --request GET 'https://amplitude.com/api/2/sessions/length?start=STARTDATE&end=ENDDATE'
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221001`.
`timeHistogramConfigBinTimeUnit`	Optional. Time unit for bucket sizes. Valid values are `hours`, `minutes`, and `seconds`.
`timeHistogramConfigBinMin`	Optional. Minimum value for bucketing, as a number. For example, `0`.
`timeHistogramConfigBinMax`	Optional. Maximum value for bucketing, as a number. For example, `600`.
`timeHistogramConfigBinSize`	Optional. Size of each bucket, as a number. For example, `60`.

timeHistogramConfigBin format

To use custom binning, specify timeHistogramConfigBinMin, timeHistogramConfigBinMax, and timeHistogramConfigBinTimeUnit. When timeHistogramConfigBinSize isn't specified, Amplitude finds the best bin sizing. For example, with timeHistogramConfigBinMin=0, timeHistogramConfigBinMax=10, and timeHistogramConfigBinTimeUnit=minutes, the final number of bins or bin bounds isn't guaranteed. With timeHistogramConfigBinSize=1, there are 10 bins and each bin size equals a minute.

When timeHistogramConfigBin parameters are invalid or missing, Amplitude uses default bins that account for behaviors such as bounce rate. The default bins, in milliseconds, are: [0, 3000), [3000, 10,000), [10,000, 30,000), [30,000, 60,000), [60,000, 180,000), [180,000, 600,000), [600,000, 1,800,000), [1,800,000, 3,600,000), [3,600,000, 86,400,000).

Session lengths have a maximum length of 1 day (86,400,000 ms).

Response

The response is a JSON object with this schema:

Attribute	Description
`series`	An array containing one array with the session counts for each bucket.
`xValues`	An array of session length interval strings (buckets), formatted as `[bucketStartInSeconds]s-[bucketEndInSeconds]s`.

json

{
   "data": {
        "series": [ 
             [0, 120408, 2261, 6984, 10778, 54529, 210614, 336605, 196235, 54148] 
        ],
        "xValues": ["0s-60s", "60s-120s", "120s-180s", "180s-240s", "240s-300s", "300s-360s", "360s-420s", "420s-480s", "480s-540s", "540s-600s"]
    }
}

Get average session length

GET https://amplitude.com/api/2/sessions/average

Get the average session length (in seconds) for each day in the specified date range.

bash

curl --location --request GET 'https://amplitude.com/api/2/sessions/average?start=20210601&end=20210630' \
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221004`.

Response

Returns a JSON object with this schema:

Attribute	Description
`series`	An array containing one array with the average session length for each day.
`seriesMeta`	An array of labels, one for each segment.
`segmentIndex`	The index of the segment, referring to its position in the right module of the chart control panel.
`xValues`	An array of date strings in `YYYY-MM-DD` format, one for each date in the specified range.

json

{
    "data": {
        "series": [
            [1204.0238276716443, 1197.4160169086904],
        ],
        "seriesMeta": [
            {"segmentIndex": 0}
        ],
        "xValues": ["2017-08-14", "2017-08-15"]
    }
}

Get average sessions per user

GET https://amplitude.com/api/2/sessions/peruser

Get the average number of sessions per user on each day in the specified date range.

bash

curl --location --request GET 'https://amplitude.com/api/2/sessions/peruser?start=&end=' \
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221004`.

Response

Returns a JSON object with this schema:

Attribute	Description
`series`	An array containing one array with the float average number of sessions per user for each day.
`seriesMeta`	An array of labels, one for each segment.
`segmentIndex`	The index of the segment, referring to its position in the right module of the chart control panel.
`xValues`	An array of date strings in `YYYY-MM-DD` format, one for each date in the specified range.

json

{
    "data": {
        "series": [
            [3.624536794878406, 3.6232302614435854]
        ], 
        "seriesMeta": [
            {"segmentIndex": 0}
        ], 
        "xValues": ["2017-08-14", "2017-08-15"]
    }
}

User composition

Get the distribution of users across values of a user property in the specified date range.

GET https://amplitude.com/api/2/composition

bash

curl --location --request GET 'https://amplitude.com/api/2/composition?start=STARTDATE&end=ENDDATE&p=PROPERTY' \
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221001`.
`p`	Required. The property to get the composition of. For built-in Amplitude properties, valid values are `version`, `country`, `city`, `region`, `DMA`, `language`, `platform`, `os`, `device`, `start_version`, and `paying`. For custom-defined user properties, format the key as `gp:name`.

Response

Returns a JSON object with this schema:

Attribute	Description
`series`	A one-element array containing the number of unique users who had the corresponding property value in the specified date range.
`seriesLabels`	The user property the chart displays.
`xValues`	An array of values the chosen property can take.

json

{ 
    "data": {
        "series": [
            [69643, 47419, 38087, 19064]
        ], 
        "seriesLabels": ["version"], 
        "xValues": ["1.0", "(none)", "1.1", "0.2"]
     }
}

Get events list

Get the list of events with the current week's totals, uniques, and % DAU (daily active users).

This endpoint returns events that are visible. Hidden events aren't returned by the API.

GET https://amplitude.com/api/2/events/list

bash

curl --location --request GET 'https://amplitude.com/api/2/events/list' \
-u '{api-key}:{secret-key}'

Response

Returns a JSON object with this schema:

Attribute	Description
`non_active`	Whether the event is marked inactive.
`value`	Name of the event in the raw data.
`totals`	The total number of times the event happened this week.
`deleted`	Whether the event is deleted.
`flow_hidden`	Whether the event is hidden from Pathfinder or Pathfinder Users.
`hidden`	Whether the event is hidden.
`display`	The display name of the event.

json

{
    "data": [
        {
            "non_active": false, 
            "value": "Add Content to Cart", 
            "totals": 1505645, 
            "deleted": false, 
            "flow_hidden": false, 
            "hidden": false, 
            "display": "Add Content to Cart"
        }, 
        {
            "non_active": false, 
            "value": "Add Friends", 
            "totals": 193167, 
            "deleted": false,
            "flow_hidden": false, 
            "hidden": false, 
            "display": "Add Friends"
        }
    ]
    ...
}

Event segmentation

Get metrics for an event with segmentation.

curl

curl --location --request GET 'https://amplitude.com/api/2/events/segmentation?e={"event_type":"YOUR%20EVENT"}&start=STARTDATE&end=DATE' \
-u '{api-key}:{secret-key}'

URL encode special characters in event types, event properties, and user property names. For example, encode Play Song as Play%20Song.

Query parameters

Name	Description
`e`	Required. Include up to two. A full event. Refer to event format. To query on a second event, use the parameter `e2`.
`m`	Optional. Non-property metrics: `uniques`, `totals`, `pct_dau`, or `average`. Defaults to `uniques`. Property metrics: `histogram`, `sums`, or `value_avg`. To use property metrics, include a valid group by value in parameter `e`. For custom formulas: `formula` (this metric supports up to two events; the second event must use the `e2` parameter).
`n`	Optional. User type, either `any` or `active`.
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221001`.
`i`	Optional. Set to -300000, -3600000, 1, 7, or 30 for real-time, hourly, daily, weekly, and monthly counts, respectively. Defaults to 1. Real-time segmentation displays up to 2 days of data, hourly segmentation displays up to 7 days of data, and daily displays up to 365 days of data.
`s`	Optional. Segment definitions (default: none). Refer to Shared query parameters.
`g`	Optional. Include up to two. The name of the property to group by. Defaults to none. For non-Amplitude custom user properties, prepend the user property name with `gp:`. For example, `country` or `gp:utm_campaign`. To query on a second property, use the parameter `g2`.
`limit`	Optional. The number of Group By values returned (default: 100). The limit is 1000.
`formula`	Optional. Required if `m` is set to `formula`. For the custom formula metric, pass in the formula here (for example, `UNIQUES(A)/UNIQUES(B)`).
`rollingWindow`	Optional. Required to use a rolling window. Pass in the number of days, weeks, or months to compute a rolling window over.
`rollingAverage`	Optional. Required to use a rolling average. Pass in the number of days, weeks, or months to compute a rolling average over.

Response

Attribute	Description
`series`	An array with one element for each group, in the same order as `seriesLabels`. Each element is an array containing the metric value for each day in `xValues`.
`seriesLabels`	An array of labels, one for each group.
`seriesCollapsed`	An array with one element for each group, in the same order as `seriesLabels`. Each element is the bar chart value in Event Segmentation, representing total unique users over a time interval.
`xValues`	An array of date strings in `YYYY-MM-DD` format, one for each date in the specified range.

json

{
    "data": {
        "series": [ 
            [273333], [190351]
        ],
        "seriesLabels": ["United States", "Germany"],
        "seriesCollapsed": [
            [
                {"value": 273333}
            ],
            [
                {"value": 190351}
            ],
        "xValues": ["2014-10-01", "2014-10-02"]
    }
}

Funnel analysis

Get funnel drop-off and conversion rates.

GET https://amplitude.com/api/2/funnels

curl

curl --location -g --request GET 'https://amplitude.com/api/2/funnels?e={"event_type":"EVENT_1"}&e={"event_type":"EVENT_2"}&start=STARTDATE&end=ENDDATE'
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`e`	Required. A full event for each step in the funnel. Refer to event format.
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221001`.
`mode`	Optional. The mode to run the funnel in: `ordered` for events in the given order, `unordered` for events in any order, and `sequential` for events in the given order with no other events between. Defaults to `ordered`.
`n`	Optional. Either `new` or `active` to specify which set of users to consider in the funnel. Defaults to `active`.
`i`	Optional. Set to -300000, -3600000, 1, 7, or 30 for real-time, hourly, daily, weekly, and monthly counts, respectively. Defaults to 1. Real-time segmentation displays up to 2 days of data, hourly segmentation displays up to 7 days of data, and daily displays up to 365 days of data.
`s`	Optional. Segment definitions. Defaults to none. Refer to Shared query parameters.
`g`	Optional. Limit: one. The name of the property to group by. Defaults to none. For non-Amplitude custom user properties, prepend the user property name with `gp:`. For example, `country` or `gp:utm_campaign`.
`cs`	Optional. The conversion window in seconds. Defaults to 2,592,000 (30 days). Conversion windows round down to the nearest day in `unordered` mode.
`limit`	Optional. The number of Group By values returned. Defaults to 100. The maximum is 1000.

Response

The response includes an array with one element per group. Each element has these fields:

Field	Description
`meta`	An array of labels, one for each segment. Includes `segmentIndex`, which is the index of the segment in the right module of the chart control panel.
`stepTransTimeDistribution`	Histogram data for each step showing how long it took users to convert through that step.
`stepPrevStepCountDistribution`	Histogram data for each step showing how many times users performed the previous step.
`bins`	Data for one histogram bucket. `start` and `end` mark the histogram bin bounds. `bin_dist` contains the users, count, or propsum for that bin.
`dayMedianTransTimes`	Median transition times by day between steps. Contains `series` (an array with one element per group, each an array of median transition times in milliseconds for each day in `xValues`), `xValues` (date strings in `YYYY-MM-DD` format), and `formattedXValues` (date strings in `Month DD` format).
`dayAvgTransTimes`	Average transition times by day between steps. Contains `series` (an array with one element per group, each an array of average transition times in milliseconds for each interval in `xValues`), `xValues` (date strings in `YYYY-MM-DD` format), and `formattedXValues` (date strings in `Month DD` format).
`stepByStep`	An array with one element per funnel step, indicating the fraction of users from the previous step who completed that step.
`medianTransTimes`	An array with one element per funnel step, indicating the median transition time between steps in milliseconds.
`cumulative`	An array with one element per funnel step, indicating the fraction of total users who completed that step.
`cumulativeRaw`	An array with one element per funnel step, indicating the number of users who completed that step.
`avgTransTimes`	An array with one element per funnel step, indicating the average transition time between steps in milliseconds.
`dayFunnels`	The number of users who completed each funnel step by day. Contains `series` (an array with one element per group, each an array of user counts for each interval in `xValues`), `xValues` (date strings in `YYYY-MM-DD` format), and `formattedXValues` (date strings in `Month DD` format).
`events`	Labels for each event in the funnel.

json

{
    "data": [
        {
            "meta": {"segmentIndex": 0},
            "dayMedianTransTimes": {
                "series": [
                    [0, 165548, 264380], [0, 164767, 269444]
                ],
                "xValues": ["2017-08-14", "2017-08-15"],
                "formattedXValues": ["Aug 14", "Aug 15"]
            },
            "dayAvgTransTimes": {
                "series": [
                    [0, 2294365, 5730478], [0, 2268879, 5700436]
                ],
                "xValues": ["2017-08-14", "2017-08-15"],
                "formattedXValues": ["Aug 14", "Aug 15"]
            },
            "stepByStep": [1.0, 0.9915120144246691, 0.9741139357951383],
            "medianTransTimes": [0, 166444, 270194],
            "cumulative": [1.0, 0.9915120144246691, 0.9658456707593803],
            "cumulativeRaw": [163054, 161670, 157485],
            "avgTransTimes": [0, 2175406, 5607243], 
            "dayFunnels": {
                "series": [
                    [125259, 123716, 118636], [126964, 125373, 119986]
                ],
                "xValues": ["2017-08-14", "2017-08-15"],
                "formattedXValues": ["Aug 14", "Aug 15"]
            },
            "events": ["Search Song or Video", "Select Song or Video", "Play Song or Video"]
        } 
    ]
}

Retention analysis

Get user retention for specific starting and returning actions.

GET https://amplitude.com/api/2/retention

bash

curl --location --request GET 'https://amplitude.com/api/2/retention?se={"event_type":"STARTEVENT"}&re={"event_type":"RETURNEVENT"}&start=STARTDATE&end=ENDDATE' \
-u '{api_key}:{secret_key}'

Query parameters

Parameter	Description
`se`	Required. Full event for the start action. Supports two `event_type` values: `_new` for new users, and `_active` for all users.
`re`	Required. Full event for the returning action. Supports one `event_type` value: `_all` for all events and `_active` for all active events.
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221001`.
`rm`	Optional. The retention type: `bracket`, `rolling`, or `n-day`. Note that `rolling` implies unbounded retention. Defaults to `n-day`.
`rb`	Optional. Required if `rm` is set to `bracket`. The days within each bracket, formatted `[[0,4]]`. For example, for a Day 0 - Day 4 bracket, the parameter value is `[[0,5]]`.
`i`	Optional. Either 1, 7, or 30 for daily, weekly, and monthly counts, respectively. Defaults to 1.
`s`	Optional. Segment definitions. Defaults to none. Refer to Segment definition.
`g`	Optional. Limit: one. The name of the property to group by. Defaults to none. For non-Amplitude custom user properties, prepend the user property name with `gp:`. For example, `country` or `gp:utm_campaign`.

Response

Field	Description
`series`	A JSON object with two keys: `dates` (an array of formatted date strings, one per date in the specified range, in descending order) and `values` (a JSON object with one key per date, where each value is an array of retention data). The first element (index 0) contains the total user count for that cohort. Subsequent elements contain retention data: element at index N+1 corresponds to retention for N intervals (days, weeks, or months, depending on `i`) out. Index 1 is Day 0 retention, index 2 is Day 1 retention, and so on.
`count`	The number of users retained in that interval.
`outof`	The total number of users in the cohort (users who performed the starting action on the date).
`incomplete`	Whether users on that date have had enough time to be retained.
`combined`	A JSON object where each value is an array of aggregated retention data across all date cohorts. The first element (index 0) contains the total user count. Subsequent elements contain retention data: element at index N+1 corresponds to retention for N intervals out. Index 1 is Day 0 retention, index 2 is Day 1 retention, and so on. This object is the deduplicated aggregate of all date cohorts from the `values` JSON object.
`seriesMeta`	An array of labels, one for each segment.
`segmentIndex`	The index of the segment, referring to its position in the right module of the chart control panel.
`eventIndex`	The index of the event, referring to which return event is selected when several are in the left module.

json

{
    "data": {
        "series": [
            {
                "dates": ["Aug 15", "Aug 14"],
                "values": {
                    "Aug 14": [
                        {"count": 12864, "outof": 12864, "incomplete": false}, {"count": 9061, "outof": 12864, "incomplete": false}, ..., {"count": 1561, "outof": 12864, "incomplete": true}
                    ],
                    "Aug 15": [
                        {"count": 14720, "outof": 14720, "incomplete": false}, {"count": 10249, "outof": 14720, "incomplete": false}, ..., {"count": 1773, "outof": 14720, "incomplete": true}
                    ],
                },
                "combined": [
                    {"count": 27584, "outof": 27584, "retainedSetId": null, "incomplete": false},
                    {"count": 19310, "outof": 27584, "retainedSetId": null, "incomplete": false},
                    ...
                    {"count": 1561, "outof": 12864, "retainedSetId": null, "incomplete": true}
                ]
            },
        "seriesMeta": [
            {"segmentIndex": 0, "eventIndex": 0}
            ]
        ]
    } 
}

User activity

Get a user summary and the user's most or least recent events. Exceeding the request limits returns 429 errors.

GET https://amplitude.com/api/2/useractivity

curl

curl --location --request GET 'https://amplitude.com/api/2/useractivity?user={amplitude_id}'
-u '{api_key}:{secret_key}'

Query parameters

Name	Description
`user`	Required. Amplitude ID of the user.
`offset`	Optional. Zero-indexed offset (from the most recent event) to start returning events from.
`limit`	Optional. Number of events to return (up to 1000). The API may return more events to avoid partial sessions. Defaults to 1000.
`direction`	Optional. `earliest` to include the user's earliest event or `latest` to include the most recent. Defaults to `latest`.

Response

The response is a JSON object with this schema:

Attribute	Description
`events`	An array of JSON objects, one for each event the user performed.
`userData`	Total statistics about the user and the user's properties.

json

{
    "userData": {
        "user_id": "myusername",
        "canonical_amplitude_id": 12345,
        "merged_amplitude_ids": [11111, 22222],
        "num_events": 142,
        "num_sessions": 23,
        "usage_time": 2570259,
        "first_used": "2015-03-14",
        "last_used": "2015-04-22",
        "purchases": 2,
        "revenue": 9.98,
        "platform": "iOS",
        "os": "ios 8.2",
        "version": "3.4.9",
        "device": "Apple iPhone",
        "device_type": "Apple iPhone 6",
        "carrier": "AT&T",
        "country": "United States",
        "region": "California",
        "city": "San Francisco",
        "dma": "San Francisco-Oakland-San Jose, CA",
        "language": "English",
        "start_version": "1.2.3",
        "device_ids": ["some-device", "some-other-device"],
        "last_location": {
            "lat": 37.133,
            "lng": -122.241
        },
        "properties": {
            "gender": "female"
        }
    },
    "events": [...]
}

User search

Search for a user by Amplitude ID, device ID, user ID, or user ID prefix. Exceeding the request limits returns 429 errors.

GET https://amplitude.com/api/2/usersearch

curl

curl --location --request GET 'https://amplitude.com/api/2/usersearch?user=USER_ID' \
-u '{api-key}:{secret-key}'

Query parameters

Name	Description
`user`	Required. Amplitude ID, Device ID, User ID, or User ID prefix.

Response

Attribute	Description
`matches`	An array of JSON objects, one for each matching user containing their Amplitude ID and User ID.
`type`	Which match type (Amplitude ID, Device ID, User ID, User ID prefix) yielded the result.

json

{
    "matches": [
        {
            "user_id": "myusername",
            "amplitude_id": 12345
        }
    ],
    "type": "match_user_or_device_id"
}

If there are no matches, the response returns a 200 response with the following body:

json

{
    "type": "nomatch",
    "matches": []
}

Real-time active users

Get active user numbers with 5-minute granularity for the last two days.

GET https://amplitude.com/api/2/realtime

curl

curl --location --request GET 'https://amplitude.com/api/2/realtime' \
-u '{api-key}:{secret-key}'

Response

Returns a JSON object with this schema:

Attribute	Description
`xValues`	An array of time strings in `HH:mm` format, one for each time interval in a day starting from the current time.
`seriesLabels`	An array of two labels: `Today` and `Yesterday`.
`series`	An array with one element for each group, in the same order as `seriesLabels`. Each element is an array containing the metric value for each day in `xValues`.

json

{
    "data": {
        "xValues": ["15:00", "15:05", "15:10", ... ],
        "seriesLabels": ["Today", "Yesterday"],
        "series": [
            [123, 144, 101, ...],
            [139, 111, 180, ...]
        ]
    }
}

Revenue lifetime value

Get the lifetime value of new users.

GET https://amplitude.com/api/2/revenue/ltv

Learn more about the Revenue LTV chart.

curl

curl --location --request GET 'https://amplitude.com/api/2/revenue/ltv?start=&end=' \
-u '{api-key}:{secret-key}'

Query parameters

Parameter	Description
`m`	Optional. One of these metrics: 0 = average revenue per user (ARPU), 1 = average realized revenue per user (ARPPU), 2 = Total Revenue, 3 = Paying Users. Defaults to 0.
`start`	Required. First date included in data series, formatted YYYYMMDD. For example, `20221001`.
`end`	Required. Last date included in data series, formatted YYYYMMDD. For example, `20221001`.
`i`	Optional. Either 1, 7, or 30 for daily, weekly, and monthly counts, respectively. Defaults to 1.
`s`	Optional. Segment definitions. Defaults to none. Refer to Segment definition.
`g`	Optional. Limit: one. The name of the property to group by. Defaults to none. For non-Amplitude custom user properties, prepend the user property name with `gp:`. For example, `country` or `gp:utm_campaign`.

Response

Returns a response containing JSON objects with this schema:

Field Description

seriesLabels An array of labels, one for each group.

series A JSON object with two keys: dates (an array of formatted date strings, one per date in the specified range, in descending order) and values (a JSON object with one key per date). Each value contains keys r1d, r2d, ..., r90d for the n-day metric values, plus count, paid, and total_amount, which indicate the total number of users, the number of paid users, and the amount paid by users for the group.

Field	Description
`seriesLabels`	An array of labels, one for each group.
`series`	A JSON object with two keys: `dates` (an array of formatted date strings, one per date in the specified range, in descending order) and `values` (a JSON object with one key per date). Each value contains keys `r1d`, `r2d`, ..., `r90d` for the n-day metric values, plus `count`, `paid`, and `total_amount`, which indicate the total number of users, the number of paid users, and the amount paid by users for the group.

json

{
    "data": {
        "seriesLabels": [""],
        "series": [
            {
                "dates": ["2021-10-04", "2021-10-03", "2021-10-02", "2021-10-01"],
                "values": {
                    "2014-10-01": {
                        "r1d": 9.99,
                        "r2d": 19.98,
                        ...
                        "r90d": 742.52,
                        "count": 110,
                        "paid": 37,
                        "total_amount": 781.39
                    },
                    ...
                }
            }
        ]
    }
}

Was this helpful?

Dashboard REST API

Considerations

Rate limits

User activity and user search limits

Endpoint costs

Shared query parameters

Event format

Filter object keys

Event format example

Segment definition

Segment definition examples

User property filter

"Who performed" filter

Export data tables

Get results from an existing chart

Path variables

Response

Get active and new user counts

Example: Get active users for a period, counted in an interval

Example: Get active users for a period, segmented by a property, counted in an interval

Query parameters

Response

Get session length distribution

Example: Get session length distribution with a custom bin for a period

Example: Get session length distribution by hours with a custom bin size for period

Query parameters

timeHistogramConfigBin format

Response

Get average session length

Query parameters

Response

Get average sessions per user

Query parameters

Response

User composition

Example: Get user composition by property for a period of time

Example: Get user composition by custom property event for a period

Query parameters

Response

Get events list

Response

Event segmentation

Example: Get any active event for a period

Example: Get two events for a period

Example: Get a custom event for a period

Example: Get event totals for a period

Example: Get event Active % for a period

Query parameters

Response

Funnel analysis

Example: Get event funnel for a series of events in a period, in any order with a specific conversion time

Example: Get event funnel for a series of events in a period, in a specific order grouped by a property

Example: Get event funnel for a series of events in a period, in a specific order, filtered by property, grouped by property

Example: Get event funnel for four events in a period

Example: Get event funnel for four events in a period, for new users, unordered

Example: Get event funnel for four events in a period, for new users, ordered

Query parameters

Response

Retention analysis

Example: Get unbounded retention for active event with another event return for a period

Example: Get weekly N-day retention for active event with another event return for a period

Example:

Query parameters

Response

User activity

Example: Get events for user with ID 123

Example: Get most recent two events for user with ID 123

Query parameters

Response

User search

Example: Search for user by device ID

Example: Search for user by Amplitude ID

Query parameters

Response

Real-time active users

Response

Revenue lifetime value

Example: LTV aggregated weekly

Example: LTV aggregated monthly for new paying users

Query parameters