Prerequisites
Before you send a request, make sure that you have the following items:requests library.
Base URL
The base URL of the Vitals API V2 ishttps://developer.amazon.com/api/appstore.
Operations
The Vitals API V2 includes the following operations and endpoints:issuesMetricSetsupports Query Issues only. A Check Freshness request for it returns404 RESOURCE_NOT_FOUND.- Query Metrics and Query Issues paths must end in
:query.
Request headers
Request rules
The rules in this section apply to the Query Metrics operation and to the Query Issues operation.Time values
Use UTC timestamps in the formatYYYY-MM-DDThh:mm:ssZ for startTime and endTime.
The time values follow these rules:
- The time range includes the time periods of
startTimeandendTime.endTimemust be the same asstartTimeor later. - For
DAILY, the API uses the UTC date. ForHOURLY, the API ignores minutes and seconds. For example,2026-08-18T14:35:00Zselects the UTC period starting at2026-08-18T14:00:00Z. startTimemust be within the latest 30 UTC dates forDAILYor the latest 15 UTC dates forHOURLY. The API counts these dates back from the freshness value. The date of the freshness value is the first of them.- The UTC date (
DAILY) or UTC hour (HOURLY) ofendTimemust not be later than the freshness value. - For a time range that breaks these rules, the API sends
400 VALIDATION_ERRORwithFIELD_OUT_OF_RANGEon the field that breaks the rule,timelineSpec.startTimeortimelineSpec.endTime. - If no freshness value is available, the query returns no rows.
- A date without a time, for example
2026-08-18 - A time with fractions of a second, for example
2026-08-18T00:00:00.000Z - A time with a time zone offset, for example
2026-08-18T00:00:00+00:00 - A time that ends with a lowercase
z
Dimensions and filters
- A filter key must name a dimension of the metric set. It need not appear in
dimensions. - Use nonempty, case-sensitive strings for filter values. A
countryCodevalue must be an uppercase ISO 3166-1 alpha-2 code, for exampleUS. The API matches any value for each key and requires every key to match. An empty array has no effect. - A breakdown omits data without a value for any requested dimension.
Pagination
To get the next page, sendnextPageToken as pageToken. Keep the request unchanged except for pageToken and, if needed, pageSize. Repeat until nextPageToken is null. Omit pageToken to start a new query.
Check Freshness
The Check Freshness operation returns the metadata of a metric set and the freshness of its data. The request has no body.Check Freshness response fields
Check Freshness request example
Check Freshness response example
Query Metrics
The Query Metrics operation returns the metrics of one metric set for each time period in the time range that has data.Query Metrics request parameters
Query Metrics request example
The dates in the Query Metrics and Query Issues request examples are illustrative. For a real request, choose dates based on Time values and Check Freshness.Query Metrics response fields
Metric objects
A metric object has one of two shapes:- Rate or count metric:
{"name": "crashRate", "value": 0.0142} - Duration metric:
{"name": "coldStartAppLaunchTime", "statistics": {"Average": 1234.5678, "P90": 1500.0000, "P95": 1800.0000}}. The four duration metrics of theappLatencyMetricSetand thereadyToUseMetricSetuse this shape. Thestatisticsobject is always present. Each statistic can benull.
0.0142 means 1.42%), counts are integers, and duration statistics are in milliseconds. A null metric value or statistic means that the API cannot calculate it. For metric meanings, see Metric values.
Additional metric rules
The following rules apply to specific metrics:- A start is slow when app launch time is at least 5 seconds for a cold start or 2 seconds for a warm start.
- For an
HOURLY7-day rate, the API combines the same UTC hour from each of the 7 days.
Query Metrics response example
In this example, the app has data only for August 17 and August 18.Duration metric example
The following example shows one row of anappLatencyMetricSet query without dimensions.
Ready-to-use availability
EachreadyToUseMetricSet response has an availability object. The responses of the other metric sets do not have this object.
AVAILABLE when one or more of the requested ready-to-use metrics has data in the time range of the query. Otherwise, the state is ACTION_REQUIRED. The API checks all pages of the query, not only the current page. These are the possible causes of ACTION_REQUIRED:
- Your app does not report that it is ready to use. On Fire OS, your app must call
Activity.reportFullyDrawn(). On Vega OS, your app must call the callback fromuseReportFullyDrawn(). For the steps, see Available metric sets. - Amazon has no ready-to-use data for your app yet.
- No freshness value is available for the aggregation period of the query.
ACTION_REQUIRED, the response can have rows. In these rows, the statistics are null.
The following example shows an ACTION_REQUIRED response without rows.
Query Issues
The Query Issues operation returns the top crash issues or the top ANR issues for the full time range. The response has one row for each issue. If you request dimensions, the response has one row for each combination of an issue and dimension values.Query Issues request parameters
metrics field. The API returns errorEventCount and affectedDeviceCount for each issue.
Query Issues request example
Query Issues response fields
resultCount or freshness. Issues are ordered by descending errorEventCount.
Query Issues response example
Implementation examples
The following examples show Python code for the Vitals API V2. Run the examples in order, in one Python session. Each example uses the functions and the variables of the examples before it.Obtain an access token
To get an access token, send aPOST request to https://api.amazon.com/auth/o2/token, with these form fields:
grant_type:client_credentialsclient_id: your client IDclient_secret: your client secretscope:adx_reporting::appstore:marketer
access_token and expires_in. The value of expires_in is the number of seconds until the token expires.
The following example keeps the token. It gets a new token 5 minutes before the token expires.
Send a request with retries
The following helper retries429 and temporary errors. On the first 401, it refreshes the token and retries if an attempt remains. For the retry rules, see Retry strategy.
Choose a time range
The following helper builds a time range that ends at the metric set’s freshness value. Choose a range within the limits in Time values.Query crash metrics
The following example gets the daily crash rate, the crash count, and the device count for each app version. The filter includes only Fire TV devices in the US and Canada.Query app launch time
The duration metrics havestatistics, not value. The following example gets the app launch times for cold starts and warm starts, for each device type.
Query slow start rate
TheslowStartRateMetricSet requires startType in dimensions. The following example gets the hourly slow start rate for the latest 24 hours, for cold starts only.
Query ready-to-use time
The following example gets the ready-to-use time and checks theavailability object.
Paginate through results
The following function gets all pages of a query. It waits 0.4 seconds between two pages to stay under the rate limit. It returns the rows and thefreshness object of the last page. For Query Issues, the second value is None, because the response has no freshness.
Query top crash issues
The following example gets the first page of the top crash issues of version code152 in the latest 14 days. The filter selects the version.
Error handling
See the following sections for how to handle errors.Error response format
The API sends a JSON body with each error response. The HTTP status code is in the status line of the response. The body does not contain the status code or the request ID.x-amzn-RequestId header. Record this value. If you contact Amazon Developer Support about a request, include this value.
Single-error example
The following response is for anHOURLY query that requests crashRate28dUserWeighted.
Multi-field validation example
The following response is for a query with"startTime": "2026-08-18" and "pageSize": -5.
Error codes
Field error codes
Common mistakes and fixes
Rate limits, retries, and best practices
As a guideline, the API permits about 3 requests per second for each developer account, with short bursts of up to 10 requests. All Vitals API V2 operations share this limit, for all your apps. The limit can change, and the API can send a429 response before you reach it. V1 of the Vitals API has a separate limit.
When you exceed the limit, the API sends a 429 RATE_LIMIT_EXCEEDED response with a Retry-After header. Wait for the number of seconds in the header before you send the request again.
Retry strategy
Thesend function sends a request again after 429, 500, 503, 504, a connection error, or a timeout, up to 3 times. If the response has a Retry-After header, the function waits for that number of seconds. Otherwise, it waits about 2, 4, and 8 seconds, plus up to 1 second of random jitter. After the first 401, the function gets a new access token and sends the request again if an attempt remains. The function does not retry other 4xx errors or failed token requests.
Production best practices
Migrate from V1
Version 1 (V1) of the Vitals API continues to operate. The following table shows the changes that you must make to move to version 2 (V2).Related topics
- Vitals API V2 Overview: Available metrics and dimensions
- App Health Insights Dashboard: Visual dashboard for the same metrics
- Reporting API Explorer: Interactive API explorer on the developer portal
- Explore the API: Link to the Reporting API Explorer in the Developer Console

