> ## 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 Rank History

> Day-by-day ranks for up to 5 apps on up to 20 keywords, and how crowded a keyword's results have been.

Two history endpoints for keywords Appeeky already tracks:

* **Apps history** charts how several apps ranked for the same keywords, day by day. Use it to see whether a competitor overtook you and when.
* **Results history** shows how many apps ranked for one keyword on each day.

Both work for the App Store and Google Play. History exists only for keywords that are tracked; add one with [Track Keyword](https://docs.appeeky.com/docs/track-keyword.md).

***

## API

| Method | Endpoint | Description | Credits |
| - | - | - | - |
| GET | `/v1/keywords/ranks/apps-history` | Daily ranks of 1–5 apps on 1–20 keywords | 2 |
| GET | `/v1/keywords/ranks/history` | Daily count of apps ranking for one keyword | 1 |

***

## Apps history

```
GET /v1/keywords/ranks/apps-history
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `appIds` | string | Yes | — | Comma-separated store ids, 1–5 (App Store numeric ids or Google Play package names) |
| `keywords` | string | Yes | — | Comma-separated keywords, 1–20 |
| `platform` | string | No | `apple` | `apple` or `google` |
| `country` | string | No | `us` | Storefront country code |
| `days` | number | No | `30` | Lookback window, 1–90 |

App Store ranks are for iPhone.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://api.appeeky.com/v1/keywords/ranks/apps-history?appIds=123456789,987654321&keywords=habit%20tracker,daily%20planner&days=30" \
  -H "X-API-Key: $APPEEKY_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "platform": "apple",
    "country": "us",
    "device": "iphone",
    "days": 30,
    "appIds": ["123456789", "987654321"],
    "keywords": [
      {
        "keyword": "habit tracker",
        "series": [
          { "date": "2026-10-28", "ranks": { "123456789": 7, "987654321": 3 } },
          { "date": "2026-10-31", "ranks": { "123456789": 5, "987654321": null } }
        ],
        "latest": { "123456789": 5, "987654321": null }
      }
    ]
  }
}
```

* `series` has one point per day the keyword was checked. Keywords aren't checked every day, so gaps between dates are normal.
* A `null` rank means the app wasn't in the ranked results that day.
* `latest` is the most recent point, for quick "who's ahead now" checks.

***

## Results history

```
GET /v1/keywords/ranks/history
```

| Name | Type | Required | Default | Description |
| - | - | - | - | - |
| `keyword` | string | Yes | — | Keyword, at least 2 characters |
| `platform` | string | No | `apple` | `apple` or `google` |
| `country` | string | No | `us` | Storefront country code |
| `device` | string | No | `iphone` | App Store only: `iphone` or `ipad` |
| `days` | number | No | `14` | Lookback window, 1–90 |

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "keyword": "habit tracker",
    "platform": "apple",
    "country": "us",
    "history": [
      { "date": "2026-10-28", "appsCount": 198 },
      { "date": "2026-10-31", "appsCount": 201 }
    ]
  }
}
```

***

## Errors

| Status | Code | When |
| - | - | - |
| 400 | `INVALID_APP_IDS` | `appIds` missing, invalid, or more than 5 |
| 400 | `INVALID_KEYWORDS` | `keywords` missing or more than 20 |
| 400 | `INVALID_KEYWORD` | `keyword` shorter than 2 characters |
| 400 | `INVALID_PLATFORM` | `platform` is not `apple` or `google` |

***

## MCP

| Tool | Description |
| - | - |
| `get_keyword_ranks_history` | Daily count of apps ranking for a keyword (1 credit) |

For one app's own rank on a keyword over time, see [Keyword Trends](https://docs.appeeky.com/docs/keyword-trends.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.