The Amp Devcenter Test Developer Hub

Welcome to the Amp Devcenter Test developer hub. You'll find comprehensive guides and documentation to help you start working with Amp Devcenter Test as quickly as possible, as well as support if you get stuck. Let's jump right in!

Get Started    

Dashboard REST API

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.

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 Notes

  • *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.
  • 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.

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 key should be formatted as "gp:name".
ParameterDescription
eA full event, potentially with property filters or group by. Events are represented as JSON objects as described below.
s (multiple)Segment definitions. Segments are represented as JSON arrays, where each element is a JSON object corresponding to a filter condition as described below.
g (up to 2)The property to group by (can only be used when there is at most one segment), for example platform

Event Format

The event parameter contains the following keys:

  • event_type (required) - The type of the event.
    • For custom events, prefix the name with "ce:" (e.g. "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 (optional) - A list of property filters.
    Each filter should be represented as a JSON object with the following keys:
    • subprop_type (required) - Either "event" or "user", indicating that the property is either an event or user property, respectively.
    • subprop_key (required) - The name of the property to filter on.
    • subprop_op (required) - The operator for filtering on specific property values,
      either "is", "is not", "contains", "does not contain", "less", "less or equal", "greater", "greater or equal", "set is", or "set is not".
    • subprop_value (required) - A list of values to filter the event property by.
  • group_by (optional) - A list of properties to group by (at most 2).
    Each group by should be represented as a JSON object with the following keys:
    • type (required) - Either "event" or "user", indicating that the property is either an event or user property, respectively.
    • value (required) - The name of the property to group by.

Example

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

Segment Definition

  • prop (required) - The name of the property to filter on.

  • For behavioral cohorts, the name of the property will be "userdata_cohort" (e.g. "userdata_cohort").

    • Example ("XYXxxzz" is the identifier from the Behavioral Cohort's URL, https://analytics.amplitude.com/org_name/cohort/XYXxxzz.)
    s=\[\{"prop":"userdata_cohort","op":"is","values":\["XYXxxzz"\]\}\]
    
  • op (required) - The operator for filtering on specific property values, either "is", "is not", "contains", "does not contain", "less", "less or equal", "greater", "greater or equal", "set is", or "set is not".

  • values (required) - A list of values to filter the segment by.

  • If you are segmenting by a cohort, the value will the cohort ID which you can find in the URL of the cohort in the platform (e.g. "5mjbq8w").

Example

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

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

ParameterDescription
CHART_ID (required)The chart ID from an existing chart (e.g. 'abc123' in the following URL: https://analytics.amplitude.com/demo/chart/abc123).

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

ParameterDescription
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001").
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004").
m (optional)Either "new" or "active" to get the desired count (default: "active").
i (optional)Either 1, 7, or 30 for daily, weekly, and monthly counts, respectively (default: 1).
s (optional)Segment definitions (default: none). Defined here.
g (optional) (up to 1)The property to group by (default: none). Defined here.

Returns

AttributeDescription
seriesAn array with one element for each group, in the same order as "seriesMeta", where each element is itself an array that contains the value of the metric on each of the days specified in "xValues".
seriesMetaAn array of labels with one for each segment.
xValuesAn array of (string) dates in the form "YYYY-MM-DD", one for each date in the specified range.

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

ParameterDescription
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001").
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004").

Returns

AttributeDescription
seriesAn array with one element which is itself an array that contains the counts (number of sessions) for each of the buckets.
xValuesAn array of the (string) session length intervals (buckets).

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

ParameterDescription
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001").
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004").

Returns

AttributeDescription
seriesAn array with one element which is itself an array that contains the average session length for each day.
seriesMetaAn array of labels with one for each segment.
segmentIndexThis represents the index of the segment, referring to its position in the right module of the chart control panel.
xValuesAn array of (string) dates formatted like "YYYY-MM-DD" with one for each in the specified date range.

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

ParameterDescription
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001").
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004").

Returns

AttributeDescription
seriesAn array with one element which is itself an array that contains the (float) average number of sessions per user for each day.
seriesMetaAn array of labels with one for each segment.
segmentIndexThis represents the index of the segment, referring to its position in the right module of the chart control panel
xValuesAn array of (string) dates formatted like "YYYY-MM-DD" with one for each in the specified date range

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

ParameterDescription
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001").
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004").
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, the key should be formatted as gp:name.

Returns

AttributeDescription
seriesA one-element array which is the number of unique users who had the corresponding property value in the specified date range.
seriesLabelsThe field that displays what user property the chart is looking at.
xValuesAn array of values the chosen property can take on.

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:

AttributeDescription
non_activeIf the event has been marked inactive or not.
valueName of the event in the raw data.
totalsThe total number of times the event has been performed this week.
deletedIf the event has been deleted or not.
flow_hiddenIf the event is hidden from Pathfinder/Pathfinder Users or not.
hiddenIf the event has been hidden or not.
displayThe display name of the event.

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

ParameterDescription
e (required, up to 2)A full event. Full description.

Note: Currently, the Dashboard REST API supports segmentation by up to two events. If you wish to query on a second event, the parameter would be "e2".
m (optional)For non-property metrics: "uniques", "totals", "pct_dau", or "average" (default: "uniques"). For property metrics: "histogram", "sums", or "value_avg" (Note: a valid "group_by" value is required in parameter e).

For custom formulas: "formula" (Note: This metric only supports up to two events currently and the second event will need to have the parameter "e2").
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001")
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004")
i (optional)Set to -300000, -3600000, 1, 7, or 30 for real-time, hourly, daily, weekly, and monthly counts, respectively (default: 1). Real-time segmentation is capped at 2 days, hourly segmentation is capped at 7 days, and daily at 365 days.
s (optional)Segment definitions (default: none). Full description.
g (optional) (up to 2)The property to group by (default: none). Full description.
limit (optional)The number of Group By values returned (default: 100). The maximum limit is 1000.
formula (optional, required if m is set to formula)If you are using the custom formula metric, you will need to pass in the formula here (e.g. "UNIQUES(A)/UNIQUES(B)").
rollingWindow (optional, required to use a rolling window)If you would like to include a rolling window, then you will need to pass in the number of days/weeks/months with which to compute a rolling window over. You can read more about this feature here.
rollingAverage (optional, required to use a rolling average)If you would like to include a rolling average, then you will need to pass in the number of days/weeks/months with which to compute a rolling average over. You can read more about this feature here.

Returns

AttributeDescription
seriesAn array with one element for each group, in the same order as "seriesLabels", where each element is itself an array that contains the value of the metric on each of the days specified in "xValues".
seriesLabelsAn array of labels, one for each group.
seriesCollapsedAn array with one element for each group, in the same order as "seriesLabels", where each element is the value of the bar chart visualization in Event Segmentation. This will give the total unique users over a certain time interval.
xValuesAn array of (string) dates in the form "YYYY-MM-DD", one for each date in the specified range.

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

ParameterDescription
e (required, multiple)A full event for each step in the funnel. Full description.
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001")
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004")
mode (optional)Either "unordered" or "ordered" to specify what mode to run the funnel in (default: "ordered"). See here for more information.
n (optional)Either "new" or "active" to specify what set of users to consider in the funnel (default: "active").
s (optional)Segment definitions (default: none). Full description.
g (optional) (up to 1)The property to group by (default: none). Full description.
cs (optional)The conversion window in seconds (default: 2,592,000 -- 30 days). Conversion windows are automatically rounded down to the nearest day in "unordered" mode.
limit (optional)The number of Group By values returned (default: 100). The maximum limit is 1000.

Returns

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

AttributeDescription
metaAn array of labels with one for each segment.

segmentIndex This represents the index of the segment, referring to its position in the right module of the chart control panel.
stepTransTimeDistributionThe histogram data of each step for how long it took users to convert through that step
stepPrevStepCountDistributionThe histogram data for each step for how many times users performed the previous step.
binsData for one histogram bucket. start and end are the start/end of the histogram bin, the data in bin_dist is the users/count/propsum for that histogram bin.
dayMedianTransTimesMedian transition times by day between steps.
seriesAn array with one element for each group, where each element is itself an array that contains the median transition time between steps in milliseconds on each of the days specified in "xValues".

xValues: An array of (string) dates in the form "YYYY-MM-DD", one for each date in the specified range. formattedXValues: An array of (string) dates in the form of "Month DD", one for each date in the specified range.
dayAvgTransTimesAverage transition times by day between steps.

series An array with one element for each group, where each element is itself an array that contains the average transition time between steps in milliseconds on each of the intervals specified in "xValues".
xValues An array of (string) dates in the form "YYYY-MM-DD", one for each date in the specified range.
formattedXValues An array of (string) dates in the form of "Month DD", one for each date in the specified range.
stepByStepAn array with one element for each step of the funnel, indicating the fraction of users from the previous step who completed that step.
medianTransTimesAn array with one element for each step of the funnel, indicating the median transition time between steps in milliseconds.
cumulativeAn array with one element for each step of the funnel, indicating the fraction of the total users who completed that step.
cumulativeRawAn array with one element for each step of the funnel, indicating the number of users who completed that step.
avgTransTimesAn array with one element for each step of the funnel, indicating the average transition time between steps in milliseconds.
dayFunnelsRepresents the number of users who completed each step of the funnel by day.

series An array with one element for each group, where each element is itself an array that contains the number of users who have completed that step in the funnel on each of the intervals specified in "xValues."
xValues An array of (string) dates in the form of "YYYY-MM-DD", one for each date in the specified range.
formattedXValues An array of (string) dates in the form of "Month DD", one for each date in the specified range
eventsLabels for each event in the funnel

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

ParameterDescription
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.
rm (optional)The retention type: bracket, rolling, or n-day. Note that rolling implies unbounded retention. (Default: n-day, no need to call it explicitly).
rb (optional, required if rm is set to bracket)The days within each bracket, formatted [0,4] (e.g. if your bracket was Day 0 - Day 4, the parameter value would be [0,5]).
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001").
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004").
i (optional)Either 1, 7, or 30 for daily, weekly, and monthly counts, respectively (default: 1).
s (optional)Segment definitions (default: none). Full description.
g (optional) (up to 1)The property to group by (default: none). Full description.

Returns

AttributeDescription
seriesA JSON object containing two keys.

dates - An array of formatted string dates, one for each date in the specified range (in descending order).
values - A JSON object with one key for each date, where each value is an array whose n-th element corresponds to the retention for n intervals (days, weeks, or months depending on i) out. This is by each interval.
countThe number of users who were retained in that interval.
outofThe total number of users in the cohort (users who performed the starting action on the date), respectively.
incompleteWhether or not users in that date have had enough time to be retained.
combinedA JSON object where each value is an array whose n-th element corresponds to the retention for n intervals (days, weeks, or months depending on i) out. This object is the deduplicated aggregate of all date cohorts from the values JSON object.
countThe number of users who were retained in that interval.
outofThe total number of users in the cohort (users who performed the starting action on the date), respectively.
incompleteWhether or not users in that date have had enough time to be retained.
seriesMetaAn array of labels with one for each segment.
segmentIndexThis represents the index of the segment, referring to its position in the right module of the chart control panel.
eventIndexThis represents the index of the event, referring to which event if you have multiple return events selected in the left module.

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

ParameterDescription
user (required)Amplitude ID of the user.
offset (optional)Zero-indexed offset to start returning events from.
limit (optional)Limit on the number of events returned (up to 1000).

Returns

AttributeDescription
eventsAn array of JSON objects, one for each event performed by the user.
userDataAggregate statistics about the user and their user properties.

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

ParameterDescription
user (required)Amplitude ID, Device ID, User ID, or User ID prefix.

Returns

AttributeDescription
matchesAn array of JSON objects, one for each matching user containing their Amplitude ID and User ID.
typeWhich match type (Amplitude ID, Device ID, User ID, User ID prefix) yielded the result.

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/[email protected]'
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

ParameterDescription
i (optional)Length of time interval. The only option available is 5 for realtime, which is also the default.

Returns

AttributeDescription
xValuesAn array of (string) times in the form "HH:mm", one for each time interval in a day starting from the current time.
seriesLabelsAn array of two labels: "Today" and "Yesterday".
seriesAn array with one element for each group, in the same order as "seriesLabels", where each element is itself an array that contains the value of the metric on each of the days specified in "xValues".

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

ParameterDescription
m (optional)One of the following metrics: 0 = ARPU, 1 = ARPPU, 2 = Total Revenue, 3 = Paying Users (default 0).
start (required)First date included in data series, formatted YYYYMMDD (e.g. "20141001").
end (required)Last date included in data series, formatted YYYYMMDD (e.g. "20141004").
i (optional)Either 1, 7, or 30 for daily, weekly, and monthly counts, respectively (default: 1).
s (optional)Segment definitions (default: none). Full description.
g (optional) (up to 1)The property to group by (default: none). Full description.

Returns

AttributeDescription
seriesLabelsAn array of labels, one for each group.
seriesA JSON object containing two keys.

"dates" - An array of formatted string dates, one for each date in the specified range (in descending order).
"values" - A JSON object with one key for each date, where each value is a JSON object with keys "r1d", "r2d", ..., "r90d" for the n-day metric values as well as the keys "count", "paid", and "total_amount", indicating the total number of users, number of paid users, and amount paid by the users for the group.

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:

AttributeDescription
labelThe label of the annotation.
dateThe date (in YYYY-MM-DD format) of the annotation.
detailsThe details associated with the annotation.

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."
        }
    ]
}

Updated 6 months ago


Dashboard REST API


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.