Dashboard Rest API - Export Amplitude Dashboard Data

Any data that can be displayed on the dashboard graphs can also be obtained via the commands below. The results are returned as JSON. The Dashboard REST API is based on whatever time zone you have set your project to in Amplitude.

In the example requests, the parameters are highlighted purple. The values in red are what you need to replace with the parameters you are specifically interested in.

Authenticate via basic authentication with the project's credentials API_Key:Secret_Key. You should literally replace the "API_Key" text with your API Key, and the "Secret_Key" text with your Secret Key. For instructions on how to find these keys, refer here.

Important Note:

• Please read the Request Limits section thoroughly. Exceeding any of these limits will return a 429 error. These limits are per project, and the 429 error will also include some information on how you are exceeding the limit.

Table of Contents

• Request Limits
• User Activity/User Search
• All Other Endpoints
• Query Parameters
• Results from an Existing Chart
• Active and New User Counts
• Session Length Distribution
• Average Session Length
• Average Sessions per User
• User Composition
• Events List
• Event Segmentation
• Funnel Analysis
• Retention Analysis
• User Activity
• User Search
• Real-time Active Users
• Revenue LTV
• Annotations

Important Note:

• You may have to URL encode special characters in the names of event types, event properties, and user properties. For example, 'Play Song' would be 'Play%20Song'. Here is an encoding reference. In addition, note that the examples in this article contain backslash syntax in order to escape characters when using curl. If you are not using curl, then you should not encode your request with backslash escape characters.

Request Limits

For each endpoint, there is a concurrent and a rate limit. The concurrent limit restricts the amount of requests you can run at the same time. The rate limit restricts the total number of queries you can run per hour. Exceeding any of these limits will return a 429 error. These limits are per project, and the 429 error will also include some information on how you are exceeding the limit.

• Concurrent Limit: You can only run up to 5 concurrent requests across all of our REST API endpoints (including cohort download).

User Activity/User Search

The User Activity and User Search endpoints have a different rate limit than all other request types.

• Rate Limit: You can run up to 360 queries per hour.

All Other Endpoints

All other endpoints take into account a concept of cost per query. We calculate cost based on the following formula:

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

Here is how we calculate each variable in the above formula:

• # of days: This is the number of days you are querying over.
• # of conditions: This is the number of segments + the number of conditions within the segments applied to the chart you are looking at. In addition, each group by will count as 4 segments. For example, the following configuration will generate 10 because we have 1 segment with 1 condition and 2 group bys applied.

• cost for the query type: Different chart types will have different costs. For all other endpoints not listed below, the cost is 1.
  • Event Segmentation: This will be equal to the number of events you are looking at in the left module.
  • Funnel Analysis: This will be the number of events you are looking at in the funnel * 2.
  • Retention Analysis: The cost for this chart is 8.
  • User Sessions: The cost for this chart is 4.

For these endpoints, here are the limits with each limit measured in the cost of each query:

• Concurrent Limit: You can run queries that collectively add up to 1000 cost at the same time.
• Rate Limit: You can run up to 36,000 cost per hour.

As an example, the following chart will generate a cost of 1800. This is calculated with cost = 30 * 10 * 6 because the chart is looking at 30 days, 1 segment with 1 condition and 2 group bys, and 3 events in the funnel.

Query Parameters

There are a few complex query parameters that are shared across multiple API endpoints and they are detailed here

Important Note:

• 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 defined user properties, the value should be formatted as "gp:name". 

{
    "event_type": "CompletedProfile",
    "filters": [
        {
            "subprop_type": "event",
            "subprop_key": "EmailVerified",
            "subprop_op": "is",
            "subprop_value": ["true"]
        }
    ],
    "group_by": [
        {
            "type": "user"
        }
    ]
}

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

platform

Results from an Existing Chart

Get JSON results from any existing (saved) chart via chart ID.

GET https://amplitude.com/api/3/chart/CHART_ID_HERE/query

Parameters

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/3/chart/CHART_ID/query'

Responses will vary depending on the chart type.

Active and New User Counts

Get the number of active or new users.

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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/users?m=active&start=20170814&end=20170815&i=1&g=country'

Example Response

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

Session Length Distribution

Get the number of sessions for each pre-defined length ("bucket") period during a specified date range.

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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/sessions/length?start=20170814&end=20170815'

Example Response

{
   "data": {
        "series": [ 
             [0, 120408, 2261, 6984, 10778, 54529, 210614, 336605, 196235, 54148] 
        ],
        "xValues": ["0 secs", "0-3 secs", "3-10 secs", "10-30 secs", "30-60 secs", "1-3 mins", "3-10 mins", "10-30 mins", "30-60 mins", "1+ hours"]
    }
}

Average Session Length

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

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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/sessions/average?start=20170814&end=20170815'

Example Response

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

Average Sessions per User

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

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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/sessions/peruser?start=20170814&end=20170815'

Example Response

{
    "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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/composition?start=20170814&end=20170815&p=version'

Example Response

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

Events List

Get the list of events with the current week's totals, uniques, and % DAU.

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

Returns

The response contains an array with one element per event. Each event has the following fields:

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/events/list'

Example Response

{
    "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.

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

Parameters

Returns

Example Requests

Returns the total number of times the event_type "CANCEL", where "stage" = "NONE", on a daily basis, between 10/01/2014 and 10/04/2014, grouped by the user property "version".

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/events/segmentation?e=\{"event_type":"Event%20Name","filters":\[\{"subprop_type":"type","subprop_key":"property","subprop_op":"is","subprop_value":\["NONE"\]\}\]\}&m=metric&start=YYYYMMDD&end=YYYYMMDD&i=1&g=property'

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/events/segmentation?e=\{"event_type":"Share%20Song","filters":\[\{"subprop_type":"event","subprop_key":"SocialChannel","subprop_op":"is","subprop_value":\["facebook"\]\}\]\}&m=totals&start=20141001&end=20141004&i=7&g=country'

Returns the total number of users who did a custom event grouped by a custom user property on a daily basis between a certain time interval. The difference in this request is that the group by is on the actual event and not across all users.

curl -u API_KEY:SECRET_KEY 'https://amplitude.com/api/2/events/segmentation?e=\{"event_type":"ce:Event%20Name","group_by":\[\{"type":"user","value":"gp:property"\}\]\}&m=uniques&start=YYYYMMDD&end=YYYYMMDD&i=1'

Returns the total number of users in a certain cohort who did a certain event on a daily basis between a certain time interval.

curl -u API_KEY:SECRET_KEY 'https://amplitude.com/api/2/events/segmentation?e=\{"event_type":"Event%20Name"\}&start=YYYYMMDD&end=YYYYMMDD&m=uniques&i=1&s=\[\{"prop":"userdata_cohort","op":"is","values":\["XYXxxzz"\]\}\]'

Returns the ratio of users who completed event A to event B on a daily basis between a certain time interval by using the custom formula metric.

curl -u API_KEY:SECRET_KEY 'https://amplitude.com/api/2/events/segmentation?e=\{"event_type":"Event%20Name%20A"\}&e2=\{"event_type":"Event%20Name%20B"\}&m=formula&formula=UNIQUES(A)/UNIQUES(B)&start=YYYYMMDD&end=YYYYMMDD&i=1'

Returns the total number of users who completed event A with two event property filters that have OR operators, with results grouped by event property.

curl -u API_KEY:SECRET_KEY 'https://amplitude.com/api/2/events/segmentation?e=\{"event_type":"Event A","filters":\[\{"subprop_type":"event","subprop_key":"Property B","subprop_op":"is","subprop_value":\["(none)","0"\]\},\{"subprop_type":"event","subprop_key":"Property C","subprop_op":"is","subprop_value":\["(none)","0"\]\}\],"group_by":\[\{"type":"event","value":"Property D"\}\]\}&m=uniques&start=20140401&end=20140408&i=1'

Important Note:

• Remember that you may have to URL encode special characters in the names of event types, event properties, and user properties. For example, 'Play Song' would be 'Play%20Song'. Here is an encoding reference. In addition, note that the examples in this article contain backslash syntax in order to escape characters when using curl. If you are not using curl, then you should not encode your request with backslash escape characters.

Example Response

{
    "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

Parameters

Returns

The response contains an array with one element per group. Each element has the following fields:

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/funnels?e=\{"event_type":"Search%20Song%20or%20Video"\}&e=\{"event_type":"Select%20Song%20or%20Video"\}&e=\{"event_type":"Play%20Song%20or%20Video"\}&start=20170814&end=20170815&n=active&mode=ordered&cs=86400'

Example Response

{
    "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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/retention?se=\{"event_type":"_new"\}&re=\{"event_type":"Play%20Song%20or%20Video"\}&start=20170814&end=20170815&i=1'

Example Response

{
    "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 their most recent 1000 events plus all of the events from their most recent session. Exceeding the request limits here will result in 429 errors.

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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/useractivity?user=12345'

Example Response

{
    "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": ["somedevice", "someotherdevice"],
        "last_location": {
            "lat": 37.133,
            "lng": -122.241
        },
        "properties": {
            "gender": "female"
        }
    },
    "events": [...]
}

User Search

Search for a user with a specified Amplitude ID, Device ID, User ID, or User ID prefix. Exceeding the request limits here will result in 429 errors.

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

Parameters

Returns

Example Requests

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/usersearch?user=12345'

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/usersearch?user=deviceID123'

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/usersearch?user=user1@email.com'

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/usersearch?user=userPrefix'

Example Response

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

Real-time Active Users

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

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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/realtime?i=5'

Example Response

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

Revenue LTV

Get the lifetime value of new users.

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

Parameters

Returns

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/revenue/ltv?m=2&start=20170814&end=20170815&i=1'

Example Response

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

Annotations

Get the annotations configured in the app.

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

Returns

The response contains an array with one element per annotation. Each annotation has the following fields:

Example Request

curl -u API_Key:Secret_Key 'https://amplitude.com/api/2/annotations'

Example Response

{
    "data": [
        {
            "label": "Version 2.4 Release",
            "date": "2016-01-01",
            "details": "Added new user properties."
        }
    ]
}