Vitals API V2 Overview
You can use the Vitals API V2 to get app health metrics and performance metrics for your Fire TV and Fire tablet apps. App health metrics include the crash rate, the app not responding (ANR) rate, and the low memory kill (LMK) rate. Performance metrics include app launch time, ready-to-use time, slow start rate, frame drop rate, and slow rendering rate.
The API puts related metrics into metric sets. All metrics in a metric set have the same freshness. You can query all metrics of a metric set together. Each metric set has dimensions, for example countryCode. You can filter the results by the values of a dimension. You can also get a breakdown of the results by dimension.
Version 2 (V2) of the Vitals API is different from version 1 (V1) in these ways:
- Each path starts with the version,
/v2/. - Time values are ISO 8601 strings in UTC, for example
2026-08-18T14:00:00Z. - Metric values are JSON numbers.
- All operations use one error format.
Amazon continues to support V1. Use V2 for new integrations. Migrate existing integrations to V2. 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, you need the following items:
- An Amazon Developer account with Admin-level credentials
- A security profile attached to the Reporting API. To create a security profile, go to My Settings > API Access in the Developer Console.
- The client ID and the client secret from the Web Settings tab of the security profile
- The LWA scope
adx_reporting::appstore:marketer - The package name of your app, for example
com.example.myapp. Your developer account must own the app.
How it works
Amazon collects crash reports and performance data from the Fire TV and Fire tablet devices that run your app. Use the metrics to find trends and to compare app versions, device models, and countries. The counts are approximate, not exact totals. Amazon calculates the metrics for each UTC day and for each UTC hour. On this page and on the Vitals API V2 Reference page, the aggregation period is the value DAILY or HOURLY. A time period is one day of a DAILY query or one hour of an HOURLY query.
- With the
DAILYaggregation period, you get one row for each UTC day. The data for a day is usually available on the next day (T-1 day). - With the
HOURLYaggregation period, you get one row for each UTC hour. The data for an hour is usually available 2–3 hours after the hour starts (T-2 hours). UseHOURLYdata to find a new problem soon after you release an app version.
Freshness
Each metric set except issuesMetricSet has a Check Freshness operation (GET). It returns the latest time period that Amazon processed for each available aggregation period.
issuesMetricSet has no Check Freshness operation. For CRASH issues, use the freshness value of crashMetricSet. For ANR issues, use the freshness value of anrMetricSet. The API orders issues by errorEventCount, highest first.
| Aggregation Period | Usual Delay | Recent Query Window |
|---|---|---|
DAILY |
T-1 day | Latest 30 UTC dates |
HOURLY |
T-2 hours | Latest 15 UTC dates |
The freshness value is the start time of the latest processed period. For example, 2026-08-18T00:00:00Z means that Amazon processed August 18 for DAILY.
Set the end of your query at or before the freshness value. Freshness doesn't tell you if your app has data for that period. Devices can send data late, so recent values can change. Query recent periods again to get the latest values.
Data queries
Use Query Metrics (POST) to get data from a metric set. Specify an aggregation period and a time range. You can also specify:
- Metrics: The metrics to return. If you omit them, the API returns all metrics that support the aggregation period.
- Dimensions: The dimensions for a breakdown, for example
versionCode. - Filter: The dimension values to include. A filter doesn't add a breakdown. The filter can use a dimension that isn't in
dimensions.
Without dimensions, you get one row for each time period with data. With dimensions, you get one row for each combination of dimension values and time period with data. The API omits time periods with no data. A metric value can still be null.
Use UTC time values in the format YYYY-MM-DDThh:mm:ssZ. The time range includes the time periods of startTime and endTime.
To get the top crash or ANR issues, use Query Issues (issuesMetricSet).
All operations share one rate limit. For more information, see Rate limits, retries, and best practices.
Available metric sets
The following table lists all available metric sets and their supported metrics.
DAILY and HOURLY, except metrics with 28d in their names. Those metrics support DAILY only. A Query Issues request has no metrics field. The API returns both metrics of issuesMetricSet for each issue.| Metric Set | Metrics |
|---|---|
crashMetricSet |
crashRate (rate): Fraction of active devices with a crash crashRate7dUserWeighted (rate): 7-day crash rate, weighted by active devices crashRate28dUserWeighted (rate): 28-day crash rate, weighted by active devices userPerceivedCrashRate (rate): Fraction of active devices with a foreground crash userPerceivedCrashRate7dUserWeighted (rate): 7-day foreground crash rate userPerceivedCrashRate28dUserWeighted (rate): 28-day foreground crash rate distinctDevices (count): Approximate active device count crashCount (count): Total crash events |
anrMetricSet |
anrRate (rate): Fraction of active devices with an ANR anrRate7dUserWeighted (rate): 7-day ANR rate, weighted by active devices anrRate28dUserWeighted (rate): 28-day ANR rate, weighted by active devices userPerceivedAnrRate (rate): Fraction of active devices with a foreground ANR userPerceivedAnrRate7dUserWeighted (rate): 7-day foreground ANR rate userPerceivedAnrRate28dUserWeighted (rate): 28-day foreground ANR rate distinctDevices (count): Approximate active device count anrCount (count): Total ANR events |
lmkMetricSet |
lmkRate (rate): Fraction of active devices with an LMK event lmkRate7dUserWeighted (rate): 7-day LMK rate, weighted by active devices lmkRate28dUserWeighted (rate): 28-day LMK rate, weighted by active devices userPerceivedLmkRate (rate): Fraction of active devices with a foreground LMK event userPerceivedLmkRate7dUserWeighted (rate): 7-day foreground LMK rate userPerceivedLmkRate28dUserWeighted (rate): 28-day foreground LMK rate distinctDevices (count): Approximate active device count lmkCount (count): Total LMK events |
issuesMetricSet |
errorEventCount (count): Total crash or ANR events for the issue affectedDeviceCount (count): Distinct devices affected |
appLatencyMetricSet |
coldStartAppLaunchTime (duration): Time to the first app window after a cold start warmStartAppLaunchTime (duration): Time to the first app window after a warm start |
readyToUseMetricSet |
coldStartReadyToUseTime (duration): Time until the app is fully drawn after a cold start warmStartReadyToUseTime (duration): Time until the app is fully drawn after a warm start |
slowStartRateMetricSet |
slowStartRate (rate): Fraction of devices with a slow start, by start type slowStartRate7dDeviceWeighted (rate): 7-day slow start rate, weighted by devices slowStartRate28dDeviceWeighted (rate): 28-day slow start rate, weighted by devices distinctDevices (count): Approximate number of devices with a start of the selected type |
fluidityMetricSet |
frameDropRate (rate): The fraction of rendered UI frames that were dropped. This metric doesn't count media playback frames. slowRenderingRate (rate): Fraction of devices with a frame drop rate above 25% slowRenderingRate7dDeviceWeighted (rate): 7-day slow rendering rate, weighted by devices slowRenderingRate28dDeviceWeighted (rate): 28-day slow rendering rate, weighted by devices distinctDevices (count): Number of devices that sent frame data |
Ready-to-use metrics need a signal from your app.
- On Fire OS, call
Activity.reportFullyDrawn()when the app is fully drawn. See Improve app startup times. - On Vega OS, use
useReportFullyDrawn()from@amazon-devices/kepler-performance-api. Call the returned callback after the main screen and initial data are ready. Call the callback again when your app becomes responsive after it returns from the background. See Measure App KPIs.
Metric values
Rates are JSON numbers from 0 through 1. Counts are integers. Durations are in milliseconds. Each duration metric has three statistics: Average, P90, and P95. The percentile values are approximate. A null value isn't 0.
distinctDevices is approximate and has a different meaning in each metric set. Don't add its values across rows or time periods. For an app-wide rate, query without a filter or dimensions.
Don't add rates from different rows. To get a rate for several dimension values, use filter without dimensions.
Dimensions
All metric sets support the first six dimensions in the following table. Only the slowStartRateMetricSet supports startType. It requires startType in dimensions. You can use each dimension for a breakdown and for a filter.
| Dimension | Type | Description | Values |
|---|---|---|---|
versionCode |
String | The version code of your app when the device recorded the data | For example, 151 |
countryCode |
String | An uppercase two-letter ISO 3166-1 alpha-2 country code | For example, US |
deviceModel |
String | The code name of the device model | For example, AFTSS |
deviceType |
String | The device family | FIRE_TV, FIRE_TABLET, or OTHER |
deviceOs |
String | The operating system of the device | FIRE_OS or VEGA_OS |
osVersion |
String | The version of the operating system | For example, PS7713/5443 |
startType |
String | The type of app start | COLD or WARM |
Related topics
- Vitals API V2 Reference: Prerequisites, authentication, API endpoints, code examples, error handling, and best practices
- Reporting API: Sales, earnings, and subscription report downloads
- App Health Insights Dashboard: Visual dashboard for the same metrics
- Explore the API: Link to the Reporting API Explorer in the Developer Console
Last updated: Oct 13, 2026
