Amazon Developer

as

Settings
Sign out
Notifications
Alexa
Amazon Appstore
Ring
AWS
Documentation
Support
Contact Us
My Cases
Devices
Build
Test
Publish
Connect
Documentation
Skip to main content
This page gives the reference information that you need to integrate the Vitals API V2. For the metric sets, the metrics, and the dimensions, see the Vitals API V2 Overview. Amazon continues to support version 1 (V1) of the Vitals API. Use V2 for new integrations. Migrate existing integrations to V2. For V1, see the Vitals API Reference. For the changes that you must make, see Migrate from V1. Use of the Vitals API is subject to the Program Materials License Agreement.

Prerequisites

Before you send a request, make sure that you have the following items: The code examples on this page use Python 3.8 or later and the requests library.

Base URL

The base URL of the Vitals API V2 is https://developer.amazon.com/api/appstore.

Operations

The Vitals API V2 includes the following operations and endpoints: The endpoints use the following path parameters:
  • issuesMetricSet supports Query Issues only. A Check Freshness request for it returns 404 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 format YYYY-MM-DDThh:mm:ssZ for startTime and endTime. The time values follow these rules:
  • The time range includes the time periods of startTime and endTime. endTime must be the same as startTime or later.
  • For DAILY, the API uses the UTC date. For HOURLY, the API ignores minutes and seconds. For example, 2026-08-18T14:35:00Z selects the UTC period starting at 2026-08-18T14:00:00Z.
  • startTime must be within the latest 30 UTC dates for DAILY or the latest 15 UTC dates for HOURLY. 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) of endTime must not be later than the freshness value.
  • For a time range that breaks these rules, the API sends 400 VALIDATION_ERROR with FIELD_OUT_OF_RANGE on the field that breaks the rule, timelineSpec.startTime or timelineSpec.endTime.
  • If no freshness value is available, the query returns no rows.
The API rejects these time values:
  • 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 countryCode value must be an uppercase ISO 3166-1 alpha-2 code, for example US. 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, send nextPageToken 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

Each row has the following 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 the appLatencyMetricSet and the readyToUseMetricSet use this shape. The statistics object is always present. Each statistic can be null.
Rates are fractions (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 HOURLY 7-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 an appLatencyMetricSet query without dimensions.

Ready-to-use availability

Each readyToUseMetricSet response has an availability object. The responses of the other metric sets do not have this object. The state is 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 from useReportFullyDrawn(). 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.
With 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

A Query Issues request does not have a metrics field. The API returns errorEventCount and affectedDeviceCount for each issue.

Query Issues request example

Query Issues response fields

The response has no 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 a POST request to https://api.amazon.com/auth/o2/token, with these form fields:
  • grant_type: client_credentials
  • client_id: your client ID
  • client_secret: your client secret
  • scope: adx_reporting::appstore:marketer
The response has 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 retries 429 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 have statistics, not value. The following example gets the app launch times for cold starts and warm starts, for each device type.

Query slow start rate

The slowStartRateMetricSet 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 the availability 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 the freshness 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 code 152 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. Each success response and each error response has an 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 an HOURLY 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 a 429 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

The send 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).
Last modified on October 13, 2026