Upcoming change — January 19, 2027
Following our recent Public API pricing update, this endpoint's request limit will change:
- Date range: Each request can cover a maximum of one year.
Please split requests covering longer periods into smaller calls.
Get historical metrics for selected keywords over a given date range. If you want to have live data for keyword metrics, please see [Keyword Metrics - Current](https://developers.apptweak.com/reference/keyword-metrics-current)
Known metrics unavailable for the selected country or device remain present as one dated null value per requested day with HTTP 200. Volume and max reach require Apple Ads country coverage on iPhone, iPad and Android; search popularity additionally requires iPhone or iPad. Result counts retain broader storefront-country coverage and are fetched independently, including in mixed requests. For example, requesting all four metrics for Bosnia and Herzegovina (ba) returns dated nulls for volume, max reach and search popularity, while results contains available result counts. Unavailable metrics do not incur datapoint credits or increase the maximum credit requirement; the request fee still applies.
See also: [Volume History - multi-countries extract](https://developers.apptweak.com/recipes/volume-history-multi-countries-extract) (Recipe)
What
volumecarries over a range
volumereturns the AppTweak Volume Estimate from August 12, 2026 onward. Earlier days keep the store-reported score, which is not rewritten, so a range spanning that date shows a step change. Requestsearch_popularityfor the App Store's raw, store-reported score.
search_popularityis only available in countries where Apple Ads is available, and returns dated null values fordevice=android: Google Play publishes no equivalent. Usevolumefor Android keyword volume.Android volume history starts on February 10, 2024.
Price
| Data | Credits | Per |
|---|---|---|
| Volume | 5 | metric |
| Results | 5 | metric |
| Max reach | 5 | metric |
| Search popularity | 5 | metric |
Any date range up to 1 year costs the same.
401Unauthorized. Unknown or missing API token.
403Forbidden. Not enough credits to perform the request.
422Validation error. Returned for invalid request parameters, including unknown metric names, unsupported storefront countries or languages, and invalid devices or dates. Known metrics unavailable for a valid country/device return dated null values instead.
500Server error, including failure of every eligible history source. No credits are charged.