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

# SEOmator API: keys, requests, errors and limits

> Call the SEOmator API with an organization API key, page through lists, read errors and stay within the rate limits, with a first request to copy.

The SEOmator API gives your scripts and apps the projects, prompts, competitors, answers and reports you see in the app. Every request goes to `https://api.seomator.com` and every response is JSON. The endpoints are listed in this tab, grouped by job.

## Authenticate

Create an organization API key on [API keys](https://docs.seomator.com/settings/api-keys.md), then send it with every request, in the `x-api-key` header or as `Authorization: Bearer`. To test a key, list your projects:

```bash x-api-key theme={null}
curl https://api.seomator.com/v1/projects \
  --header "x-api-key: sk_..."
```

```bash Bearer theme={null}
curl https://api.seomator.com/v1/projects \
  --header "Authorization: Bearer sk_..."
```

A working key returns your projects as JSON. A key reaches only the organization it was created in. What a **Read only** and a **Read and write** key can do: [Access levels](https://docs.seomator.com/settings/api-keys.md#access-levels).

## IDs and projects

IDs start with their type, for example `proj_…` for a project. Where a path takes a project `{id}`, you can also pass the project's slug: its domain with dots as dashes, for example `example-com`.

## Lists

List endpoints return one page at a time.

**limit** `integer` (default: 25)

How many items to return, from 1 to 100.

**cursor** `string`

The `nextCursor` of the previous page. Leave it out to get the first page.

**nextCursor** `string | null`

Pass it as `cursor` to get the next page. `null` when you have every item.

Short lists come back whole, without paging: brands, topics, keywords, brand suggestions and Search Console properties.

## Reports

Reports are `POST` requests. Send the period (`startDate`, `endDate`) and the filters in the JSON body, the same filters as the app's filter bar: [Filter reports](https://docs.seomator.com/reports/filters.md). What each metric in a report means: [Metrics](https://docs.seomator.com/reports/metrics.md).

## Caching

Every `GET` response has an `ETag`. Send it back in `If-None-Match`, and an unchanged response comes back as `304 Not Modified` with no body.

## Errors

An error has an HTTP status and a body like this:

```json theme={null}
{
  "error": {
    "code": "not_found",
    "message": "Project proj_123 not found.",
    "requestId": "8f2b1c3d4e5a6b7c-FRA"
  }
}
```

**error** `object` *required*

**properties**

**code** `string` *required*

One of the codes in the table below.

**message** `string` *required*

What went wrong, in plain words.

**requestId** `string` *required*

Identifies the request. Include it when you contact support.

| Code | Status | What happened |
| - | - | - |
| `bad_request` | 400 | The request is not valid. The message says which field is wrong. |
| `unauthorized` | 401 | The key is missing, revoked or wrong. |
| `insufficient_credits` | 402 | The credit balance can't cover the action. |
| `plan_limit` | 402 | The action goes over a limit of your plan. |
| `forbidden` | 403 | The key's access level doesn't allow the action. |
| `not_found` | 404 | The item doesn't exist, or the key can't see it. |
| `conflict` | 409 | The action clashes with the item's current state. |
| `rate_limit_exceeded` | 429 | Too many requests. Wait a minute and try again. |
| `internal_server_error` | 500 | Something went wrong on SEOmator's side. |
| `service_unavailable` | 503 | SEOmator or a service it uses is busy. Try again in a minute. |

## Rate limits

A key can send up to 120 requests a minute, and an organization up to 600 a minute across all its keys and members. Over the limit, the API answers `429` with `rate_limit_exceeded`.

## Related

> [card] [API keys](https://docs.seomator.com/settings/api-keys.md)
>
> Create, name and revoke keys.

> [card] [MCP setup](https://docs.seomator.com/mcp/setup.md)
>
> Use SEOmator from Claude, ChatGPT and other AI tools instead.

> [card] [Metrics](https://docs.seomator.com/reports/metrics.md)
>
> What every number in a report means.

> [card] [Plans and credits](https://docs.seomator.com/getting-started/plans.md)
>
> What credits pay for and what each plan includes.


## Related topics

- [API keys: connect scripts and MCP clients](https://docs.seomator.com/settings/api-keys.md)
- [Add a keyword](https://docs.seomator.com/api-reference/ai-visibility/add-a-keyword.md)
- [Remove a keyword](https://docs.seomator.com/api-reference/ai-visibility/remove-a-keyword.md)


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