> ## 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.

# Track Keyword

> Add a keyword to the tracking list so historical rank data is collected for it.

```
POST /v1/keywords/track
```

Adds a keyword to your tracking list. Tracked keywords accumulate historical rank snapshots over time, which powers the [Keyword Trends](/docs/keyword-trends) and [Visibility](/docs/keyword-visibility) endpoints.

***

## Request Body

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "keyword": "puzzle game",
  "platform": "apple",
  "country": "us"
}
```

| Field    | Type   | Required | Description                                                                      |
| -------- | ------ | -------- | -------------------------------------------------------------------------------- |
| keyword  | string | Yes      | Keyword to track (min 2 characters)                                              |
| platform | string | No       | `apple` (default) or `google` for Google Play — see [Platforms](/docs/platforms) |
| country  | string | No       | ISO country code (default `us`)                                                  |

***

## Code Examples

<CodeGroup>
  ```bash curl theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.appeeky.com/v1/keywords/track" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"keyword": "puzzle game"}'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch("https://api.appeeky.com/v1/keywords/track", {
    method: "POST",
    headers: {
      "X-API-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ keyword: "puzzle game" }),
  });
  const { data } = await res.json();
  console.log(data.message); // "Keyword added to tracking list"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests

  res = requests.post(
      "https://api.appeeky.com/v1/keywords/track",
      json={"keyword": "puzzle game"},
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  print(data["message"])  # "Keyword added to tracking list"
  ```
</CodeGroup>

***

## Response

**Status: `201 Created`**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": {
    "keyword": "puzzle game",
    "message": "Keyword added to tracking list"
  }
}
```

| Field   | Type   | Description          |
| ------- | ------ | -------------------- |
| keyword | string | The tracked keyword  |
| message | string | Confirmation message |

***

<Tip>
  **Idempotent upsert**: If the keyword already exists in the tracking list, it is updated to active status. You can safely call this endpoint multiple times for the same keyword without creating duplicates.
</Tip>

<Note>
  **Auto-tracking**: Keywords you query through `GET /v1/keywords/ranks` are also added to your tracking list automatically once they've been queried more than once. If you already use the ranks endpoint for keyword research, many keywords will be tracked for you — no need to call this endpoint separately for those.
</Note>

***

## Errors

| Status | Code             | When                              |
| ------ | ---------------- | --------------------------------- |
| 400    | INVALID\_KEYWORD | Keyword shorter than 2 characters |
| 401    | UNAUTHORIZED     | Missing or invalid API key        |
| 429    | RATE\_LIMITED    | Too many requests — slow down     |
| 500    | DB\_ERROR        | Database operation failed         |