# An SEO API for rankings, audits and search data.

URL: https://serpel.app/developers/api

Updated: 2026-10-10

An SEO API gives your code access to rankings, audit results and search data without a dashboard. Serpel’s REST API covers rank tracking, site audits, AI visibility, keyword research, search data and reports under `/api/v1`, with JSON responses and bearer-token authentication. It is the same API that the dashboard and the CLI use.

## What the SEO API gives you

- **One API, every area:** Projects, rankings, audits, AI visibility, search data, keyword research, reports and billing sit behind the same base path.
- **Scoped tokens:** 18 scopes, optional project limits and expiry dates let you give a script only what it needs.
- **Jobs for long work:** Crawls, rank checks, AI checks and monitoring runs return a job that you can poll.
- **Predictable responses:** A `data` envelope, `pagination` on lists and one error format across every endpoint.
- **Costs you can see:** Estimate an operation before you run it and read the credit ledger afterwards.
- **A machine-readable index:** `GET /api/v1` lists every endpoint by area and needs no authentication.

## What can you do with the Serpel SEO API?

The API follows the structure of the product. Each area has endpoints to read data and, where it makes sense, to start work. The dashboard and the CLI call the same endpoints with the same permission checks.

| Area | What you can do | Main scopes |
| --- | --- | --- |
| Projects | Create projects, change settings such as device, depth, schedule and JavaScript rendering, and manage members. | `projects:read`, `projects:write` |
| Rank tracking | Add keywords, run checks, read positions, history, stored results, locations and competitors. | `rankings:read`, `rankings:write` |
| Site audit | Start crawls, read pages, issues, Core Web Vitals and crawl comparisons. | `audit:read`, `audit:write` |
| AI visibility | Add prompts, run ChatGPT and AI Overview checks, read citations and sources. | `rankings:read`, `rankings:write` |
| Search data | Connect Google and Bing, read clicks, impressions, CTR and position. | `projects:read`, `projects:write` |
| Keyword research | Research keywords, manage keyword lists, import and export. | `keywords:read`, `keywords:write` |
| Recommendations | Read prioritised opportunities and change their status. | `recommendations:read`, `recommendations:write` |
| Codebase | Upload and read route snapshots of a Next.js project. | `codebase:read`, `codebase:write` |
| Reports and monitoring | Run monitoring, read reports, manage recipients and webhooks. | `rankings:write`, `projects:read`, `projects:write` |
| Billing | Read the balance and ledger, estimate costs and manage agent spending. | `billing:read`, `billing:write` |

## How do you run a site audit through the API?

`POST /projects/{id}/crawls` starts a crawl and answers with `202`, a job and the flag `alreadyRunning`. Poll `GET /jobs/{id}` until the job has succeeded, then read `GET /projects/{id}/issues`. It returns the score, the counts by severity and one group per issue type with `why`, `fix` and the number of affected URLs. Add `severity`, `category` or `q` to filter.

For detail, `GET /crawls/{id}/pages` lists the crawled URLs and `GET /crawls/{id}/pages/{pageId}` returns links, issues and signals for rendering, hreflang, structured data and soft 404s. `GET /crawls/{id}/web-vitals` returns Core Web Vitals per URL and device, and `GET /projects/{id}/crawls/compare` shows new, fixed and changed issues between two crawls. The [site audit](https://serpel.app/features/site-audit) page explains the 94 checks.

## How do authentication, responses and errors work?

Send an API token as `Authorization: Bearer <token>`. Create tokens in the dashboard under Settings, API tokens, or with `serpel tokens create`. A token carries only the scopes you choose, can be limited to specific projects and can expire. Tokens begin with `vsk_` and are shown once. OAuth access tokens issued for the MCP server are rejected by the REST API.

Responses use a `data` envelope. List responses add `pagination` with `limit`, `offset` and `total`, and accept `limit`, `offset` and, on most lists, `q` for search. Errors share one format with `code`, `message` and `details`.

| HTTP status | Error code |
| --- | --- |
| 400 | `validation_error`, `bad_request` |
| 401 | `unauthorized` |
| 402 | `insufficient_credits` |
| 403 | `forbidden`, `plan_limit` |
| 404 | `not_found` |
| 409 | `conflict` |
| 429 | `rate_limited`, with a `Retry-After` header |
| 502 and 503 | `provider_error`, `provider_not_configured` |

Paid synchronous calls, such as keyword research, accept an `Idempotency-Key` header. A retry with the same key neither calls the data provider nor books credits again.

## What does the SEO API cost?

Reading data is free. Calls that fetch live data book credits from a public price list. One credit is worth €0.01 including VAT, and new accounts start with 100 credits.

| Operation | Unit | Credits |
| --- | --- | --- |
| Scheduled monitoring, up to top 50 | per keyword | 2 |
| Scheduled monitoring, top 100 | per keyword | 3 |
| Rank check right now, up to top 50 | per keyword | 5 |
| Rank check right now, top 100 | per keyword | 9 |
| ChatGPT answer check | per question | 2 |
| Google AI Overview check | per question | 2 |
| Keyword research | per search | 8 + 4 per 50 results |
| Keyword research by domain | per domain | 4 + 2 per 50 results |
| Site crawl | per 20 pages | 1 |

`POST /billing/estimate` returns the cost of an operation without booking it, and `GET /billing/ledger` lists every booking. A request that your balance can’t cover fails with `402`. Plans and credit packs are on the [pricing](https://serpel.app/pricing) page.

## Where do you find the endpoint list?

`GET /api/v1` returns an index of all endpoints grouped by area, and `GET /api/health` reports whether the service and its database are up. Neither needs authentication. For rankings in particular, see the [rank tracking API](https://serpel.app/developers/rank-tracking-api).

## Frequently asked questions

### Can I use the Serpel SEO API on the free plan?

Yes. API access is part of every plan, including the free one. You only pay credits for calls that fetch live data, such as rank checks, AI checks, keyword research and crawls.

### Which API calls start long-running work?

Crawls, rank checks, AI visibility checks and monitoring runs return `202` and a job. Poll `GET /jobs/{id}` for the status. Keyword research and keyword list refreshes run synchronously and accept an `Idempotency-Key`.

### Can an AI agent use the API?

Yes, with a scoped token. Agents that speak MCP can also use the [MCP server](https://serpel.app/developers/mcp), which signs in with OAuth and exposes read-only tools, so no token has to be copied into a configuration file.

### How does Serpel handle rate limits?

Requests above the limit get `429` with `rate_limited`, a `Retry-After` header and `details.retryAfterSeconds`. Calls that cost credits are limited more tightly than reads, so build retries around the header.