Important Note:
This article has been moved to our Developer Center, and will no longer be updated on this site. Here is the newest version of our 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.
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
- 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 key should be formatted as "gp:name".
Parameter | Description | |
---|---|---|
e |
A full event, potentially with property filters or group by.
Each filter should be represented as a JSON object with the following keys:
Each group by should be represented as a JSON object with the following keys:
Example: { "event_type": "CompletedProfile", |
|
s (multiple) |
Example: [ { |
|
g (up to 2) |
The property to group by (can only be used when there is at most one segment). Examples: 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
Parameter | Description |
---|---|
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
Parameter | 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"). |
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). Full description. |
g (optional) (up to 1) | The property to group by (default: none). Full description. |
Returns
Attribute | Description |
---|---|
series | An 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". |
seriesMeta | An array of labels with one for each segment. |
xValues | An 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
Parameter | 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"). |
Returns
Attribute | Description |
---|---|
series | An array with one element which is itself an array that contains the counts (number of sessions) for each of the buckets. |
xValues | An 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
Parameter | 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"). |
Returns
Attribute | Description |
---|---|
series | An array with one element which is itself an array that contains the average session length for each day. |
seriesMeta |
An array of labels with one for each segment.
|
xValues | An 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
Parameter | 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"). |
Returns
Attribute | Description |
---|---|
series | An array with one element which is itself an array that contains the (float) average number of sessions per user for each day. |
seriesMeta |
An array of labels with one for each segment.
|
xValues | An 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
Parameter | 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"). |
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
Attribute | Description |
---|---|
series | A one-element array which is the number of unique users who had the corresponding property value in the specified date range. |
seriesLabels | The field that displays what user property the chart is looking at. |
xValues | An 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:
Attribute | Description |
---|---|
non_active | If the event has been marked inactive or not. |
value | Name of the event in the raw data. |
totals | The total number of times the event has been performed this week. |
deleted | If the event has been deleted or not. |
flow_hidden | If the event is hidden from Pathfinder/Pathfinder Users or not. |
hidden | If the event has been hidden or not. |
display | The 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
Parameter | Description |
---|---|
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 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
Attribute | Description |
---|---|
series | An 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". |
seriesLabels | An array of labels, one for each group. |
seriesCollapsed | An 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. |
xValues | An 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
Parameter | Description |
---|---|
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:
Attribute | Description |
---|---|
meta |
An array of labels with one for each segment.
|
stepTransTimeDistribution |
The histogram data of each step for how long it took users to convert through that step |
stepPrevStepCountDistribution |
The histogram data for each step for how many times users performed the previous step. |
bins |
Data 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. |
dayMedianTransTimes |
Median transition times by day between steps.
|
dayAvgTransTimes |
Average transition times by day between steps.
|
stepByStep | An array with one element for each step of the funnel, indicating the fraction of users from the previous step who completed that step. |
medianTransTimes | An array with one element for each step of the funnel, indicating the median transition time between steps in milliseconds. |
cumulative | An array with one element for each step of the funnel, indicating the fraction of the total users who completed that step. |
cumulativeRaw | An array with one element for each step of the funnel, indicating the number of users who completed that step. |
avgTransTimes | An array with one element for each step of the funnel, indicating the average transition time between steps in milliseconds. |
dayFunnels |
Represents the number of users who completed each step of the funnel by day.
|
events | Labels 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
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. |
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
Attribute | Description |
---|---|
series | A JSON object containing two keys:
|
seriesMeta |
An array of labels with one for each segment.
|
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. You can change the offset to get the previous events. Exceeding the request limits here will result in 429 errors.
GET https://amplitude.com/api/2/useractivity
Parameters
Parameter | Description |
---|---|
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
Attribute | Description |
---|---|
events | An array of JSON objects, one for each event performed by the user. |
userData | Aggregate 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
Parameter | Description |
---|---|
user (required) | Amplitude ID, Device ID, User ID, or User ID prefix. |
Returns
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. |
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
Parameter | Description |
---|---|
i (optional) | Length of time interval. The only option available is 5 for realtime, which is also the default. |
Returns
Attribute | Description |
---|---|
xValues | An array of (string) times in the form "HH:mm", 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", 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
Parameter | Description |
---|---|
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
Attribute | Description |
---|---|
seriesLabels | An array of labels, one for each group. |
series | A JSON object containing two keys:
|
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:
Attribute | Description |
---|---|
label | The label of the annotation. |
date | The date (in YYYY-MM-DD format) of the annotation. |
details | The 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."
}
]
}