---
title: "Read stored keyword metric observations over time"
method: GET
path: "/hive/keywords/{term}/metrics/history"
tags: ["Hive"]
---

# Read stored keyword metric observations over time

`GET /hive/keywords/{term}/metrics/history`

## Request

- Base URL: `https://storelift.net/v1`
- URL: `https://storelift.net/v1/hive/keywords/{term}/metrics/history`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Read a keyword's stored daily history: the search results, the difficulty score and the Apple popularity recorded on each day. Past difficulty values stay as they were recorded. Failed and incomplete days are marked as such; a day without a stored record is not a zero or a verified absence. Follow pagination.nextCursor with the same keyword, storefront and days. Each series is paged on its own, with up to 200 records per page. This GET reads stored history only and never starts a measurement. Requires the full Hive Explorer product; Android is explicitly unsupported. 10 credits for up to 7 days, 20 for up to 30, 40 for up to 90.

## Path parameters

- `term` string, required

## Query parameters

- `country` string
- `platform` 'ios'
- `days` integer
- `cursor` string

## Response `200`

OK

- HiveKeywordMetricHistory
  - `metricReadVersion` unknown, required
  - `historical` unknown, required
  - `country` string, required
  - `platform` 'ios', required
  - `term` string, required
  - `from` string, date, required
  - `to` string, date, required
  - `days` object[], required
    - `day` string, date, required
    - `apps` integer, required
    - `difficulty` HiveMetricObservation, required
      - `status` 'fresh' | 'stale' | 'pending' | 'absent' | 'error' | 'unmeasured' | 'restricted', required
      - `kind` 'observed' | 'estimated', required
      - `value` number, nullable, required
      - `current` boolean, required
      - `source` string, nullable, required
      - `sourceObservedAt` union, required: Original source observation time; a read or model calculation does not update it.
        - string, date-time
        - string, date
      - `observedAtPrecision` unknown, required
      - `checkedAt` string, date-time, nullable, required
      - `period` object, nullable, required
        - `kind` 'week' | 'day'
        - `start` string, date
      - `modelVersion` string, nullable, required
      - `evidence` object, nullable, required: Source-bound evidence, observation ID and available hashes. parsed_json_v1 describes a hash of parsed JSON, not raw response bytes.
      - `lastAttempt` object, nullable, required: Independent from a retained observation: a retry error does not erase an earlier valid value.
        - `status` 'pending' | 'error'
        - `checkedAt` string, date-time, nullable
        - `attemptId` string
    - `sourceObservedAt` union, required
      - string, date-time
      - string, date
    - `observedAtPrecision` 'instant' | 'day', required
    - `popularity` object: That day's popularity: the same number the dashboard shows for that day. `legacy` days have no comparable value.
      - `value` integer, nullable, required
      - `status` 'measured' | 'unmeasured' | 'legacy' | 'source_error', required
  - `popularity` object[], required
    - `week` string, date, required
    - `revisionId` string, nullable, required
    - `popularity` Popularity, required (unresolved $ref)
  - `readStatus` object, required
  - `measurementStarted` unknown, required
  - `coverage` object, required
    - `requestedDays` integer, required
    - `returnedDays` integer, required
    - `missingDays` string[], nullable, required: Null when a source error or unfinished page prevents establishing the missing days.
    - `metrics` object, required
    - `retrievalComplete` boolean, required: All database sources read successfully with no remaining pages; does not claim every day was measured.
    - `complete` boolean, required
  - `pagination` object, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required

## Other responses

- `400`: A parameter is missing or malformed.
- `401`: No key, or the key is not valid.
- `402`: This month's credits are used up.
- `403`: The key's plan or scopes do not cover this call.
- `404`: No such app, or Storelift has not measured it yet.
- `429`: Too many requests.

---

[API](https://skmtc.dev/storelift/apis/storelift-api.md) · [All operations](https://skmtc.dev/storelift/apis/storelift-api/llms.txt) · [OpenAPI document](https://skmtc.dev/storelift/apis/storelift-api/revisions/4489f2d077a4?raw)