SEOmator API: keys, requests, errors and limits

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, then send it with every request, in the x-api-key header or as Authorization: Bearer. To test a key, list your projects:

curl https://api.seomator.com/v1/projects \
  --header "x-api-key: sk_..."

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.

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.

integer

default:25

How many items to return, from 1 to 100.

string

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

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. What each metric in a report means: Metrics.

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:

{
  "error": {
    "code": "not_found",
    "message": "Project proj_123 not found.",
    "requestId": "8f2b1c3d4e5a6b7c-FRA"
  }
}

object

required

Hide properties

string

required

One of the codes in the table below.

string

required

What went wrong, in plain words.

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.

API keys

Create, name and revoke keys.

MCP setup

Use SEOmator from Claude, ChatGPT and other AI tools instead.

Metrics

What every number in a report means.

Plans and credits

What credits pay for and what each plan includes.

Overview

Endpoints

SEOmator API: keys, requests, errors and limits

Authenticate

IDs and projects

Lists

Reports

Caching

Errors

Rate limits

API keys

MCP setup

Metrics

Plans and credits

​Authenticate

​IDs and projects

​Lists

​Reports

​Caching

​Errors

​Rate limits

​Related

API keys

MCP setup

Metrics

Plans and credits

Authenticate

IDs and projects

Lists

Reports

Caching

Errors

Rate limits

Related