REST API

An SEO API for rankings, audits and search data.

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.

  • REST and JSON
  • Scoped bearer tokens
  • Jobs for long work
  • Credit-based pricing
Start for freeRead the docs
Start a site audit and read the errors
curl -X POST "https://serpel.app/api/v1/projects/$PROJECT_ID/crawls" \
  -H "Authorization: Bearer $SERPEL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"maxPages":100}'

curl "https://serpel.app/api/v1/projects/$PROJECT_ID/issues?severity=error" \
  -H "Authorization: Bearer $SERPEL_TOKEN"

❯

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.

AreaWhat you can doMain scopes
ProjectsCreate projects, change settings such as device, depth, schedule and JavaScript rendering, and manage members.projects:read, projects:write
Rank trackingAdd keywords, run checks, read positions, history, stored results, locations and competitors.rankings:read, rankings:write
Site auditStart crawls, read pages, issues, Core Web Vitals and crawl comparisons.audit:read, audit:write
AI visibilityAdd prompts, run ChatGPT and AI Overview checks, read citations and sources.rankings:read, rankings:write
Search dataConnect Google and Bing, read clicks, impressions, CTR and position.projects:read, projects:write
Keyword researchResearch keywords, manage keyword lists, import and export.keywords:read, keywords:write
RecommendationsRead prioritised opportunities and change their status.recommendations:read, recommendations:write
CodebaseUpload and read route snapshots of a Next.js project.codebase:read, codebase:write
Reports and monitoringRun monitoring, read reports, manage recipients and webhooks.rankings:write, projects:read, projects:write
BillingRead 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 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 statusError code
400validation_error, bad_request
401unauthorized
402insufficient_credits
403forbidden, plan_limit
404not_found
409conflict
429rate_limited, with a Retry-After header
502 and 503provider_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.

OperationUnitCredits
Scheduled monitoring, up to top 50per keyword2
Scheduled monitoring, top 100per keyword3
Rank check right now, up to top 50per keyword5
Rank check right now, top 100per keyword9
ChatGPT answer checkper question2
Google AI Overview checkper question2
Keyword researchper search8 + 4 per 50 results
Keyword research by domainper domain4 + 2 per 50 results
Site crawlper 20 pages1

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

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

Updated 10 Oct 2026

Keep reading