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

# Tracked Keywords

> List, add, and remove keywords you track for each app

Manage the keywords tracked for any app in your list. Tracked keywords power the keyword rank monitoring shown on the **Keywords** tab in the appeeky.com dashboard.

<Info>
  All Tracked Keyword endpoints cost **0 credits** and require the `apps:read` scope for reads and `apps:write` for writes.
</Info>

***

## List Tracked Keywords

```
GET /v1/user/apps/:appId/keywords
```

Returns all keywords tracked for a given app.

**Path Parameters:**

| Name    | Type   | Description                              |
| ------- | ------ | ---------------------------------------- |
| `appId` | number | Numeric App Store ID of your tracked app |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.appeeky.com/v1/user/apps/6443843426/keywords" \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/keywords",
    { headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  const { data } = await res.json();
  ```

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

  res = requests.get(
      "https://api.appeeky.com/v1/user/apps/6443843426/keywords",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**Response (200 OK):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "data": [
    {
      "id": "7e4a1c90-...",
      "keyword": "aso tool",
      "country": "us",
      "language": "en",
      "created_at": "2026-03-19T15:47:06.270736+00:00"
    }
  ]
}
```

***

## Add a Tracked Keyword

```
POST /v1/user/apps/:appId/keywords
```

Start tracking a keyword for an app.

**Path Parameters:**

| Name    | Type   | Description                              |
| ------- | ------ | ---------------------------------------- |
| `appId` | number | Numeric App Store ID of your tracked app |

**Request Body:**

| Field      | Type   | Required | Description                              |
| ---------- | ------ | -------- | ---------------------------------------- |
| `keyword`  | string | Yes      | The keyword to track (e.g. `"aso tool"`) |
| `country`  | string | No       | ISO country code (default: `"us"`)       |
| `language` | string | No       | ISO language code (default: `"en"`)      |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.appeeky.com/v1/user/apps/6443843426/keywords" \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"keyword": "aso tool", "country": "us", "language": "en"}'
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/keywords",
    {
      method: "POST",
      headers: {
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({ keyword: "aso tool", country: "us", language: "en" }),
    }
  );
  const { data } = await res.json();
  ```

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

  res = requests.post(
      "https://api.appeeky.com/v1/user/apps/6443843426/keywords",
      headers={"X-API-Key": "YOUR_API_KEY"},
      json={"keyword": "aso tool", "country": "us", "language": "en"},
  )
  data = res.json()["data"]
  ```
</CodeGroup>

**Response (201 Created):** Returns the created keyword row.

***

## Remove a Tracked Keyword

```
DELETE /v1/user/apps/:appId/keywords/:keywordId
```

Stop tracking a keyword.

**Path Parameters:**

| Name        | Type   | Description                              |
| ----------- | ------ | ---------------------------------------- |
| `appId`     | number | Numeric App Store ID of your tracked app |
| `keywordId` | string | UUID of the tracked keyword row          |

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X DELETE "https://api.appeeky.com/v1/user/apps/6443843426/keywords/7e4a1c90-..." \
    -H "X-API-Key: YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const res = await fetch(
    "https://api.appeeky.com/v1/user/apps/6443843426/keywords/7e4a1c90-...",
    { method: "DELETE", headers: { "X-API-Key": "YOUR_API_KEY" } }
  );
  ```

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

  requests.delete(
      "https://api.appeeky.com/v1/user/apps/6443843426/keywords/7e4a1c90-...",
      headers={"X-API-Key": "YOUR_API_KEY"},
  )
  ```
</CodeGroup>

**Response (200 OK):**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{ "data": { "success": true } }
```

***

## Errors

| Status | Code                 | When                                               |
| ------ | -------------------- | -------------------------------------------------- |
| 400    | `BAD_REQUEST`        | `keyword` field missing or `appId` is not a number |
| 403    | `FORBIDDEN`          | Key scope does not allow this operation            |
| 404    | `USER_APP_NOT_FOUND` | `appId` is not in your tracked list                |
| 404    | `NOT_FOUND`          | Keyword row not found                              |
| 409    | `DUPLICATE`          | Keyword already tracked for this app + country     |