SEO API for developers

The MetricSpot SEO API runs the same 154-rule on-page + AI-readability audit as our dashboard, over plain HTTP. Bring your own language: curl, Node, Python, PHP, anything that speaks HTTPS. The same Bearer keys also work with our MCP server.

Try the SEO API right now, no signup, no token, just curl:

curl -s -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}' | jq .total_score

No card needed. Results in 30 seconds.

Try every call from your browser

OpenAPI 3.1 reference with live request examples for all 12 endpoints.

Open API reference →

Authenticate with a Bearer token

Every authenticated endpoint accepts a token in the Authorization header: Authorization: Bearer ms_live_xxx. Mint a key at app.metricspot.com/settings/api-keys (up to 10 per account). Token-authenticated calls require the Pro plan and count against your 5,000/month quota. The anonymous audit endpoint below works with no key at all, rate-limited to 1 audit per IP per 24 hours. The same ms_live_ keys work for both this REST API and the MetricSpot MCP server.

curl

Anonymous endpoint, no token. Returns the full audit envelope inline.

curl -X POST https://app.metricspot.com/api/public/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

Node (fetch)

Works in Node 18+, Bun, Deno, and modern browsers. No dependencies.

const res = await fetch("https://app.metricspot.com/api/audits", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer ms_live_xxx",
  },
  body: JSON.stringify({ url: "https://example.com" }),
});
const audit = await res.json();

Python (httpx)

requests works identically; swap httpx.post for requests.post.

import httpx

res = httpx.post(
    "https://app.metricspot.com/api/audits",
    headers={"Authorization": "Bearer ms_live_xxx"},
    json={"url": "https://example.com"},
)
audit = res.json()

PHP

Standard cURL extension, available in every PHP install since 4.0.

<?php
$ch = curl_init("https://app.metricspot.com/api/audits");
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json",
    "Authorization: Bearer ms_live_xxx",
  ],
  CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com"]),
  CURLOPT_RETURNTRANSFER => true,
]);
$audit = json_decode(curl_exec($ch), true);

Twelve endpoints, the whole audit engine

Every endpoint runs the same 154-rule audit and the same 15 score modules as app.metricspot.com. JSON in, JSON out. The anonymous trial endpoint requires no key; the other eleven accept a Bearer token from your dashboard.

POST /api/public/audit
No auth

Anonymous audit

Run a one-shot SEO and AI-readability audit on any public URL. Returns scores across 15 modules and 154 checks, plus actionable findings. No account required. Rate-limited to 1 audit per IP per 24 hours.

POST /api/audits
Bearer required

Queue full audit

Queue a full SEO and AI-readability audit. Includes Core Web Vitals from Google PageSpeed Insights, and organic traffic if GA4 and Google Search Console are linked. Responds immediately with audit_id and status: queued.

GET /api/audits/:id
Bearer required

Get audit

Fetch a previously queued audit by id. Returns the 15 module scores (0-100), the total score, every finding with severity and recommendation text, plus links to the HTML and PDF reports.

GET /api/audits
Bearer required

List audits

List the account's audits, most recent first, deduplicated by URL. Returns audit_id, url, status, total_score, has_ga, has_gsc, created_at. Default limit 24, max 100.

DELETE /api/audits/:id
Bearer required

Delete audits for URL

Delete all audits matching the URL of the given audit_id. Returns 204 on success.

PATCH /api/audits/reorder
Bearer required

Reorder audits

Set display position of audits in the dashboard. Body: { "url_order": ["https://a.com", "https://b.com", ...] } (max 200 URLs). Returns 204.

GET /api/audits/history
Bearer required

Audit history

Return up to 50 historical audits for one URL. Useful for tracking score drift over time. Query: ?url=<encoded-url>.

GET /api/audits/usage
Bearer required

Audit usage

Return current month's audit quota: audits_remaining, audits_used, plan_limit, reset_at.

POST /api/audits/:id/pdf
Bearer required

Render branded PDF

Kick off a branded PDF render for a completed audit. Body: { "language": "en", "brand_id": 42 } (both optional). Returns 201 with { pdf: { id, status: "pending" } }. Pair with GET /api/pdfs/:id to poll.

GET /api/pdfs/:id
Bearer required

Poll PDF status

Returns { pdf: { id, status, download_url } }. If Accept: application/pdf and status is ready, returns the PDF binary directly.

GET /api/pdfs/:id/download
Bearer required

Download PDF

Direct download of a completed PDF with Content-Disposition: attachment.

GET /api/audits/:id/report
Bearer required

Preview HTML report

Render the audit report as branded HTML (the same template the PDF is rendered from). Useful for embedding in a client portal iframe before downloading the PDF. Query: ?lang=en&brand_id=42.

REST API or MCP server: which fits your stack

Both interfaces talk to the same audit engine, with the same keys and the same data. Pick REST when you're writing plain HTTP from CI, scripts, or no-code tools; pick MCP when an AI agent needs to discover and chain tools on its own.

Use case Manual SEO audit Other SEO APIs MetricSpot MCP MetricSpot REST API
CI/CD on every PR Not feasible at PR cadence Possible but expensive per call, brittle JSON shapes Overkill: MCP shines for interactive agents, not headless jobs One curl in a GitHub Action, comment the score delta on the PR
No-code tools (Zapier, n8n, Make) Manual export, copy-paste Custom HTTP block, hand-mapped fields, brittle when schema shifts No MCP support in mainstream no-code platforms today Standard HTTP block with Bearer auth, JSON response maps cleanly
Polyglot stack (Go, Ruby, Java) Not applicable Need an SDK per language, often community-maintained MCP client libraries exist mainly for TypeScript and Python Any language with an HTTPS client works on day one
Internal scheduled jobs Hours per month, easy to skip Per-call pricing, often per-keyword or per-domain Works, but a stdio subprocess is awkward inside cron Plain HTTPS from cron, Kubernetes CronJob, or Lambda
AI agent workflows Human in every loop Agents can call REST, but need hand-written tool wrappers Built for this: tool descriptions and schemas auto-discovered Possible, but you'll write the agent glue code yourself
White-label PDF in your SaaS Manual export, manual rebrand Usually only on the highest tier Available via get_audit_pdf, designed for agent flows POST /api/audits/:id/pdf then GET /api/pdfs/:id, embed in your UI

How the MetricSpot SEO API compares to DataForSEO and Serpstack

DataForSEO is a full-stack SEO data marketplace; Serpstack is a SERP-scraping API; MetricSpot is a focused on-page + AI-readability audit API. Same three-letter category, different shape of value. Pick whichever matches the job you're actually doing.

What you compare DataForSEO Serpstack MetricSpot SEO API
Primary job to be done Massive data marketplace: SERPs, keywords, backlinks, on-page Scrape Google SERP HTML on demand Run a full on-page + AI-readability audit on a URL, get scores and fixes
What you get back from one call Endpoint-specific JSON; on-page audit returns ~30 tags/issues SERP listings, ads, related queries, no on-page evaluation Total score, 15 module scores (0-100), every finding across 154 rules, severity, recommendation text
Pricing model Per-call, varies by endpoint ($0.0006-$0.002 each), prepaid balance Tiered monthly: 100 free / $30 for 5K / up to $200 for 50K SERPs Flat $49/mo Pro = 5,000 API calls, no per-call math
Anonymous trial endpoint No, signup + $1 deposit required 100 calls/mo free with signup + access key Yes, 1 audit/IP/24h with zero signup, full audit JSON
AI-readability / LLM-era checks Not in the on-page module Not applicable (SERP only) Dedicated module: llms.txt, schema for AI, citation-friendly content, semantic clarity
White-label branded PDF Not provided Not provided POST /api/audits/:id/pdf returns a branded PDF with your logo and colors
MCP server for AI agents No official MCP No official MCP Yes, same Bearer keys, same audit engine, Claude Code + Cursor + ChatGPT compatible
Auth style HTTP Basic with login + password (less common in modern stacks) API key in query string (?access_key=…) Standard Authorization: Bearer ms_live_xxx header

REST API pricing

The REST API is included on Pro $49/mo. Pro accounts get 5,000 API calls per month against any of the twelve token-authenticated endpoints. The anonymous audit endpoint is free for everyone (rate-limited to 1 per IP per 24h). Free and Starter accounts can browse the docs and mint tokens, but token-authenticated calls return 403 until upgraded to Pro. The same ms_live_ keys work for both this REST API and the MetricSpot MCP server, against the same shared monthly quota.

Free

$0/mo

Try the platform. No card, no commitment.

  • ·10 audits per month (1 per site per 24h)
  • ·All ten score modules
  • ·PDF download with our branding
  • ·Multilingual reports

Starter

$29/mo

For freelancers running monthly reports.

  • ·Up to 5 tracked domains
  • ·50 audits per month
  • ·Fully white-labeled PDF reports
  • ·Custom brand kit (logo, color, footer)

Pro

$49/mo

For agencies, freelancers, and resellers.

  • ·Everything in Starter
  • ·Scheduled re-audits (weekly, biweekly or monthly)
  • ·Competitor comparison reports (up to 3 competitors)
  • ·Unlimited tracked domains

See plan limits and prices →

What developers build with the REST API

Concrete patterns we see from teams already shipping with the API. Every example uses the same tools and the same Bearer token.

  • •CI/CD: audit every preview deploy on PR open, post a comment with the score delta versus main, fail the build if the score drops more than 5 points.
  • •Zapier, n8n, Make: trigger an audit when a new lead lands in your CRM, post the total score and top 3 findings to a Slack channel, attach the branded PDF.
  • •Internal monitoring: schedule a nightly audit of your top 50 URLs, pipe the module scores into a Grafana panel, alert when a category drops.
  • •White-label SaaS: queue an audit on user demand, render the branded PDF, embed the JSON findings in your own UI without hosting the audit engine yourself.
  • •QA gates: block a deploy if the AI-readability module dips below the threshold you committed to with your client, with the failing rules in the build log.
  • •Reporting: pull GET /api/audits/history?url= after every audit to ship a trend chart of the score over time, paired with the latest branded PDF.

Writing plain HTTP from a script or CI runner is one path. If you're driving the audit from an AI agent (Claude Code, Cursor, ChatGPT, Gemini), our SEO MCP server exposes the same tools over Model Context Protocol with auto-discovered schemas: same engine, same keys, no glue code.

FAQ

Is the REST API free?

The anonymous audit endpoint (POST /api/public/audit) is free with no account required, rate-limited to 1 audit per IP per 24 hours. The eleven token-authenticated endpoints require the Pro plan at $49/mo, which includes 5,000 API calls per month at no extra cost.

How is this different from the MCP server?

Same audit engine, same 154 rules across 15 modules, same Bearer keys. The REST API is plain HTTP for humans writing code: curl, fetch, requests, anything. The MCP server speaks Model Context Protocol so AI agents (Claude Code, Cursor, ChatGPT, Gemini) can auto-discover tools, schemas, and auth. Use REST for CI, scripts, and no-code tools; use MCP for agent workflows.

Can I use it with no-code tools like Zapier?

Yes. Any no-code platform with a generic HTTP block works: Zapier (Webhooks by Zapier), n8n (HTTP Request node), Make (HTTP module), Pipedream, Retool. Set the URL to https://app.metricspot.com/api/audits, method to POST, add Authorization: Bearer ms_live_xxx to the headers, and send {"url": "https://example.com"} as JSON. The response maps cleanly to native fields in every platform we tested.

What languages have official SDKs?

None yet. All you need is an HTTPS client and JSON parsing, which every modern language has built in. A thin JavaScript and TypeScript SDK is on the roadmap; until then the four code samples above cover ~90% of integrations we see. If you want an SDK in a specific language, open an issue at github.com/MetricSpot.

How do I authenticate?

Send Authorization: Bearer ms_live_xxx on every authenticated call. Tokens are prefixed with ms_live_ and shown once at creation time; the dashboard stores only a hash. Treat them like any other secret: never commit them, rotate them if exposed, scope one key per integration so you can revoke individually. The dashboard caps each account at 10 active keys.

Where do the API keys come from?

Mint them at app.metricspot.com/settings/api-keys after signing up for any plan, including Free. Each key is shown once; copy it into your secret store immediately. The same keys work for both this REST API and the MetricSpot MCP server, so you only manage one set of credentials across both integration paths.

Is the data the same as MetricSpot's dashboard?

Yes. Every endpoint runs through the same audit engine that powers app.metricspot.com: the same 154 rules across 15 modules, the same severity assignments, the same recommendation text. The PDF report from POST /api/audits/:id/pdf is the same one you can download from the dashboard.

What are the rate limits?

The anonymous endpoint is capped at 1 audit per IP per 24 hours. API access requires Pro $49/mo. Pro includes 5,000 API calls per month. Free and Starter do not include API access. The anonymous endpoint remains free (1 per IP per 24h).

What happens if I exceed 5,000 calls in a month?

The endpoint returns HTTP 429 with body { error: "quota_exceeded", used: 5000, limit: 5000 }. The quota resets at the start of the next calendar month. If you need a higher quota, contact us via the support form and we'll work out a custom tier.

Stop writing SEO reports by hand.

Run an audit, brand the PDF, send to your client. In five minutes.

Start your first audit