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

# Get Keywords Summary

> Retrieve how many tracked keywords rank in each position band, and how ranks moved.

Returns totals for the keywords in the token's workspace: how many rank in the top 3, top 10 and so on, and how many moved up or down compared with the previous period. This endpoint only reads data.

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

## Parameters

Takes the same filters as [List Keywords](https://slatehq.com/docs/api-reference/keyword-tracker/list-keywords.md), without paging.

**Authorization** `string` *required*

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

**status** `string`

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

**search** `string`

Count keywords whose text contains this value.

**country** `string`

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

**from** `string`

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

**to** `string`

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

## Response

Returns `200 OK` with this object:

**totalKeywords** `number` *required*

Number of keywords counted.

**rankingDistribution** `object` *required*

Keywords per band of your site's average rank in the period. The bands don't overlap.

**rankingDistribution object**

**top3** `number` *required*

Average rank 1–3.

**top10** `number` *required*

Average rank above 3, up to 10.

**top20** `number` *required*

Average rank above 10, up to 20.

**top50** `number` *required*

Average rank above 20, up to 50.

**top100** `number` *required*

Average rank above 50.

**noRank** `number` *required*

Your site didn't rank for the keyword in the period.

**notRanking** `number` *required*

`top100` plus `noRank`. Kept for older clients.

**rankingMovement** `object` *required*

Keywords whose average rank changed compared with the previous period.

**rankingMovement object**

**improved** `number` *required*

Average rank got better (a lower number).

**declined** `number` *required*

Average rank got worse (a higher number).

**newRanked** `number` *required*

Ranked in this period but not in the previous one.

**lost** `number` *required*

Ranked in the previous period but not in this one.

**period** `object` *required*

The period and the previous period of the same length used for the comparison: `from`, `to`, `previousFrom`, `previousTo`.

## 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/summary?status=tracked" \
  -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/summary",
    headers={"Authorization": "Bearer slat_YOUR_TOKEN"},
    params={"status": "tracked"},
)
summary = response.json()
```


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