> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Keyword Suggestion History

> Per-day appearance log for one Apple autocomplete suggestion.

```
GET /v1/keywords/suggestions/history
```

For one suggestion (e.g. `"ai chat"`), returns the per-day record of every prefix that surfaced it in Apple's autocomplete, plus the best rank Apple placed it in. Use this to confirm whether a suggestion is sticky or a one-day flicker, and to understand which prefix paths users follow to discover it.

***

## Query Parameters

| Name       | Type   | Required | Default | Description                    |
| ---------- | ------ | -------- | ------- | ------------------------------ |
| suggestion | string | Yes      | —       | Exact autocomplete suggestion  |
| country    | string | No       | `us`    | ISO 3166-1 alpha-2 storefront  |
| days       | number | No       | `30`    | Lookback window in days, 3–180 |

***

## Response

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "suggestion": "ai chat",
    "country": "us",
    "windowDays": 30,
    "firstSeen": "2026-04-04",
    "lastSeen": "2026-04-21",
    "isCurrentlyVisible": true,
    "series": [
      { "date": "2026-04-04", "bestRank": 9, "prefixes": ["a", "ai"], "appearances": 2 },
      { "date": "2026-04-05", "bestRank": 7, "prefixes": ["a", "ai", "ai "], "appearances": 3 },
      { "date": "2026-04-21", "bestRank": 3, "prefixes": ["a", "ai", "ai c"], "appearances": 4 }
    ],
    "trend": {
      "direction": "promoted",
      "startRank": 9,
      "endRank": 3,
      "rankImprovement": 6,
      "newPrefixes": ["ai c"]
    },
    "interpretation": "Apple promoted 'ai chat' from rank 9 to rank 3 — strong demand signal. New prefix coverage: ai c."
  },
  "meta": {
    "lastScrapedAt": "2026-04-21T00:00:00Z",
    "dataAgeHours": 4,
    "source": "stored",
    "freshness": "fresh"
  }
}
```

`isCurrentlyVisible` is `true` when the suggestion appeared in today's snapshot — a quick way to confirm whether the trend is still live before acting on it.

### `trend`

Window-over-window read of how Apple's perception of the suggestion is moving:

| Field           | Type           | Meaning                                                                                                                                                                                                      |
| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| direction       | string         | `promoted` (rank improved by ≥ 2), `demoted` (worsened by ≥ 2), `stable`, `fresh` (only one day of data), `unknown` (no observations).                                                                       |
| startRank       | number \| null | Best rank on the first day of the window.                                                                                                                                                                    |
| endRank         | number \| null | Best rank on the last observed day.                                                                                                                                                                          |
| rankImprovement | number \| null | `startRank − endRank` — positive = improved (lower rank number = higher in dropdown).                                                                                                                        |
| newPrefixes     | string\[]      | Prefixes seen in the most recent 7 days that weren't seen earlier in the window — Apple expanding the suggestion into new prefix neighbourhoods is the strongest possible "demand rising" signal we can see. |

`interpretation` is a one-line plain-English summary of the trend — safe to surface directly in a UI and useful for LLM agents.

The response-level `meta` envelope describes data freshness — see [Keyword Metrics → meta envelope](/docs/keyword-metrics#meta-envelope-response-level) for the schema.

### Data freshness

The suggestion archive is refreshed daily per storefront, so the response reflects the most recent overnight snapshot. Use the response-level `meta` envelope above to read the exact `lastScrapedAt` and `freshness` band for each call.

## Credit Cost

2 credits per request.

## Use Cases

* Decide whether to invest in ranking for a suggestion based on its history (sticky vs one-off).
* Detect when a previously-strong suggestion stops being surfaced (signal of changing search behaviour).
* Build a "discovery path" view: which prefixes users type to reach the suggestion.