API & MCP

serp.ac has two ways to work with your data from outside the app. The REST API is for scripts, reseller panels and your own tools. The MCP server lets AI assistants such as Claude or Cursor read your rankings, AI visibility and links, and add to them when you allow it. Both use the same API keys, limits and quotas.

This guide is for developers, agencies that resell indexing, and anyone who wants to ask an AI assistant about their SEO data.

How it works

• API keys are created under Settings → API. Only the account owner and admins can manage them. See Team & roles.
• Every key starts with sk_live_ and is shown only once, when you create it. serp.ac stores only a hash of the key, so a lost key can't be recovered. Revoke it and create a new one.
• A key acts with the full rights of the account that created it. Anyone who has it can use your projects and quotas, so keep it secret.
• You can have up to 20 active keys per account. Each key can make up to 120 requests per minute.
• Requests and responses are JSON. Send the key in the Authorization header on every request: Authorization: Bearer sk_live_....
• The API follows your plan exactly like the dashboard: the same keyword, prompt and link limits, AI engines and monthly quotas. An active plan or free trial is required.

The base URL is shown at the top of the API reference on the Settings → API page (your serp.ac address followed by /api/v1).

Create a key step by step

1. Open Settings → API.
2. In API keys, type a name you'll recognize later, for example "Reseller panel".
3. Click Create key.
4. Copy the key right away. The message says "Copy it now — it won't be shown again."
5. Store it in a password manager or your server's secret settings, never in public code.
6. Test it with a quick call:

curl https://serp.ac/api/v1/usage \
  -H "Authorization: Bearer sk_live_..."

7. Check the key list later: it shows each key's start (sk_live_xxxx…), Created, Last used and Status.
8. If a key leaks or is no longer needed, click Revoke. Apps that use it stop working immediately.

Endpoints

Method	Path	What it does
GET	/api/v1/usage	Plan, subscription status and monthly indexer quotas
GET	/api/v1/projects	Your projects (id, name, domain, country, language)
POST	/api/v1/index/submit	Submit URLs to the indexer
POST	/api/v1/index/check	Check whether URLs are indexed
GET	/api/v1/index/jobs/:id	A job's status and the status of each URL
POST	/api/v1/keywords	Start tracking SERP keywords in a project
GET	/api/v1/prompts	Allowed AI engines, plus each project's brand names, competitors and tracked prompts
POST	/api/v1/prompts	Add AI prompts to a project
GET	/api/v1/links?source_domain=…	Purchased links you track on a publisher's domain
POST	/api/v1/links	Add a purchased link to Link management
GET	/api/v1/maps/campaigns	Maps campaigns with their latest scan results
GET	/api/v1/maps/scans?campaign_id=…	Scan history and grid results of one Maps campaign
GET	/api/v1/keyword-data	This month's keyword lookup quota
POST	/api/v1/keyword-data	Search volume, CPC, competition, difficulty, intent and 12-month trend

GET /api/v1/balance still works for older integrations, but it's deprecated. Use /api/v1/usage instead.

A few details worth knowing:

• Indexing: send {"urls": [...]} with up to 10,000 URLs per request. project_id is optional, and duplicate URLs are removed. Each URL uses 1 indexer URL (submit) or 1 index check (check), first from the monthly quota and then from usage packs. If there isn't enough quota, nothing is charged. Poll the job until its status is done. See the Indexer guide.
• Keywords: project_id plus keywords (up to 100) or a single keyword. device (desktop or mobile) and location are optional; the location defaults to the project's country.
• Prompts: project_id plus prompts (up to 50) or a single prompt. engines is optional (chatgpt, perplexity, gemini, claude, ai_mode) and defaults to the engines your plan includes. Prompts that are already tracked are reported back and left unchanged.
• Links: project_id, source_url and target_url are required. Anchor, rel, price, billing cycle, dates, vendor, tags and notes are optional. The first check runs within about a minute.
• Keyword data: up to 20 keywords per request. Cached keywords are free; others count against your monthly keyword lookup quota.

Errors

Errors always have the same shape:

{"error": {"code": "quota_exceeded", "message": "…"}}

HTTP	Code	Meaning
400	invalid_json, invalid_urls, too_many_urls…	The request body isn't valid
401	unauthorized	Missing, invalid or revoked API key
402	quota_exceeded, limit_reached	Not enough quota, a plan limit was reached, or there's no active plan
403	account_suspended	The account is suspended
404	not_found, project_not_found	The job, project or campaign isn't in your account
409	already_tracked	That purchased link is already tracked in the project
429	rate_limited	More than 120 requests per minute for this key

A 402 quota_exceeded response from the indexer also includes available, the number of URLs you can send right now. Buy a usage pack on Billing or wait for the monthly reset. For a 429, wait and retry; the response includes a Retry-After header.

MCP server for AI assistants

serp.ac runs a remote Model Context Protocol server at /api/mcp on your serp.ac address. Connect it once, and your assistant can answer questions like "which keywords dropped this week?" from your real data. If you allow it, the assistant can also add keywords, prompts and links.

• It works with Claude, Cursor, ChatGPT, VS Code, Windsurf and any other client that supports the Streamable HTTP transport and can send the Authorization header.
• It uses the same API keys, rate limit and quotas as the REST API.
• Tools that change data or use quota are marked, and assistants are told to ask you first. To expose only the read tools, add ?readonly=1 to the server URL. Read-only is a setting of the connection, not of the key.

The MCP setup guide has the step-by-step setup for each client and the full list of tools.

Tips

• Create a separate key for each app or client. Then you can revoke one without breaking the others, and Last used shows which ones are still active.
• Call GET /api/v1/usage before sending a large indexing batch to see available (remaining monthly quota plus packs).
• For read-only dashboards or assistants, connect MCP with ?readonly=1 so nothing can change your account by accident.
• Usage packs never expire and are only used after the monthly quota runs out. See Billing & plans.

FAQ

I lost my API key. Can I see it again?

No. serp.ac only stores a hash of each key, so it can't be shown again. Revoke the old key and create a new one.

Can editors or viewers create API keys?

No. Only the account owner and admins can create or revoke keys. A key always carries the full rights of the account, whoever created it.

Do API calls use the same quotas as the app?

Yes. Index submits and checks, keyword data lookups, and keyword, prompt and link limits are shared between the app, the REST API and the MCP server.

Is usage returned if Google doesn't index a submitted URL?

No. Usage is only returned when a job fails because of a technical problem on our side. Submissions are verified about 3 days later.

Which AI assistants work with the MCP server?

Any MCP client that supports the Streamable HTTP transport and can send an Authorization header, including Claude, Cursor, ChatGPT, VS Code and Windsurf. Clients that only support stdio can use the mcp-remote bridge described in the MCP guide.

Related guides

• MCP server setup and tools
• Indexer
• Chrome extension
• Team & roles