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

# List Keywords

> Retrieve the keywords tracked in your workspace, with their latest and average ranks.

Returns one page of keywords from the token's workspace. Use it to read the ranks Slate already tracks, for example to copy them into a spreadsheet once a day. This endpoint only reads data.

> [!NOTE]
>
> Every request needs an API token in the `Authorization` header. The token decides the workspace.

## Parameters

**Authorization** `string` *required*

Bearer token. Format: `Bearer slat_<your-token>`.

**status** `string`

Filter by tracking status. One of: `tracked`, `paused`. Leave it out to get both.

**search** `string`

Return keywords whose text contains this value.

**country** `string`

Return keywords tracked in this country, for example `US`.

**from** `string`

Start of the period for average ranks, in `YYYY-MM-DD` format. Send it together with `to`. Default: 14 days ago.

**to** `string`

End of the period for average ranks, in `YYYY-MM-DD` format. Default: today (UTC).

**sortBy** `string`

Sort field. One of: `keyword`, `latestRank`, `avgRank`, `volume`, `clicks`, `impressions`, `ctr`.

**sortDir** `string` (default: asc)

Sort direction. One of: `asc`, `desc`. Used with `sortBy`.

**page** `integer` (default: 1)

Page number, starting at 1.

**pageSize** `integer` (default: 20)

Keywords per page. Range: 1–200. A value outside the range falls back to 20.

## Response

Returns `200 OK` with this object:

**items** `object[]` *required*

The keywords on this page.

**keyword object**

**id** `number` *required*

Keyword ID. Use it with [Get Keyword Rank History](https://slatehq.com/docs/api-reference/keyword-tracker/get-keyword-rank-history.md).

**keywordText** `string` *required*

The keyword as entered.

**trackingStatus** `string` *required*

`active` when the keyword is tracked, `paused` when tracking is paused.

**ownedRank** `number`

Your site's best rank in the keyword's latest check. Missing when your site didn't rank.

**avgRank** `number`

Your site's average rank between `from` and `to`.

**previousAvgRank** `number`

Your site's average rank in the period of the same length that ends the day before `from`.

**targetPageRank** `number`

Rank of the page you assigned to the keyword, when you assigned one.

**primaryPageUrl** `string`

The page you assigned to the keyword.

**countries** `string[]`

Countries the keyword is tracked in.

**volumeMonthly** `number`

Monthly search volume, when available.

**lastCheckedAt** `string`

When Slate last checked the keyword's rank, in ISO 8601 format.

**total** `number` *required*

Number of keywords that match the filters, across all pages.

**page** `number` *required*

The page returned.

**pageSize** `number` *required*

Keywords per page.

**period** `object` *required*

The periods used for `avgRank` and `previousAvgRank`.

**period object**

**from** `string` *required*

Start of the period.

**to** `string` *required*

End of the period.

**previousFrom** `string` *required*

Start of the previous period.

**previousTo** `string` *required*

End of the previous period.

## Errors

| Status | Cause |
| - | - |
| `401` | The token is missing, malformed, revoked, or expired. |

See [Errors](https://slatehq.com/docs/api-reference/errors.md) for the response format.

## Example

```bash cURL theme={null}
curl -s "https://api.slatehq.ai/keyword-tracker/api/public/v1/keywords?status=tracked&page=1&pageSize=100" \
  -H "Authorization: Bearer slat_YOUR_TOKEN"
```

```python Python theme={null}
import requests

response = requests.get(
    "https://api.slatehq.ai/keyword-tracker/api/public/v1/keywords",
    headers={"Authorization": "Bearer slat_YOUR_TOKEN"},
    params={"status": "tracked", "page": 1, "pageSize": 100},
)
keywords = response.json()["items"]
```


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