curl -X POST https://seonio.com/api/v1/site-audit/start \ -H "Content-Type: application/json" \ -H "X-API-Key: $SEONIO_API_KEY" \ -d '{"country": "us", "domain": "example.com"}'
{
"audit_id": "019a4f2e-7c31-7d02-a6b5-3e8f1c2d4a90",
"domain": "example.com",
"country": "us",
"status": "queued",
"free_audit": true,
"price": "$0",
"eta_seconds": 300,
"poll_after_seconds": 30,
"url": "https://seonio.com/site-audit/example.com?country=us"
}What to send and what comes back
Step 1: start a site audit of a domain in one country: up to 100 of the site's pages checked for technical, on-page, content, speed, backlinks and AI visibility issues, with Site Health and a score per area. It uses one of your plan's free site audits this month while one is left, else costs $12 from your balance, taken at the start. A failed audit is refunded in full, or its free audit given back. One audit per site (domain and country) per 30-day period, counted from its last finished audit: sooner is a 409 with next_audit_at and the last audit's audit_id, which you can read free. While an audit of the site runs, a repeat call returns it without a second charge (safe to retry after a timeout); while another start of the site is still being set up, the call is a 503 with Retry-After. free_only with no free audit left is a 409. None of these is charged. Audits started over the API never add tasks to your SEO agent's board. The audit includes an AI Visibility Report of the site at no extra charge. The audit runs in the background, in two calls: 1. POST /api/v1/site-audit/start checks the price, starts the audit of a domain in a country and returns an audit_id. 2. POST /api/v1/site-audit/result (free) with that audit_id, or with the same domain and country: poll every 30 seconds. An audit usually takes a few minutes; eta_seconds estimates the rest. It ends done, partial (an area could not be checked) or failed (refunded in full, or the free audit given back). The audit's page on seonio.com (url) shows the same audit.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
domain |
string | required | The site's domain, e.g. example.com (www. is folded in; a subdomain is audited as its own site). A bare public suffix such as co.uk is refused. |
country |
string | optional | One of Seonio's 50 countries, as a two-letter code (default "us"; "uk" is accepted and returned as "gb"): the market the keyword numbers are for.
50 supported countriesdzAlgeriaarArgentinaauAustraliaatAustriabdBangladeshbeBelgiumbrBrazilbgBulgariacaCanadaczCzechiadkDenmarkegEgyptfiFinlandfrFrancedeGermanyghGhanagrGreecehuHungaryinIndiaidIndonesiaieIrelanditItalyjpJapankeKenyamyMalaysiamxMexicomaMorocconlNetherlandsnzNew ZealandngNigerianoNorwaypkPakistanphPhilippinesplPolandptPortugalroRomaniasaSaudi ArabiarsSerbiasgSingaporezaSouth AfricaesSpainlkSri LankaseSwedenchSwitzerlandthThailandtrTurkiyeaeUnited Arab EmiratesgbUnited Kingdom (also uk, returned as gb)usUnited StatesvnVietnam |
free_only |
boolean | optional | Optional, default false. True starts the audit only as one of your plan's free site audits: when none is left, the call is a 409 and nothing is charged (send it when your user approved a free audit, so it never becomes a $12 charge). |
Response
| Field | Type | Description |
|---|---|---|
audit_id |
string | The audit's id. |
domain |
string | The site's domain as stored. |
country |
string | The country's ISO code. |
status |
string | "queued", "running", "finishing", "done", "partial" or "failed". |
free_audit |
boolean | True when the audit used one of your plan's free site audits this month (nothing charged). |
price |
string | "$0" for a free site audit, else "$12". |
eta_seconds |
integer | null | Estimated seconds left while it runs (an estimate, not a promise); 0 once ended. |
poll_after_seconds |
integer | null | When to call again; null once the audit has ended. |
url |
string | The audit's page on seonio.com (signed in to this account). |
Copy, paste, add your key
The same request in cURL, Python and Node.js.
curl -X POST https://seonio.com/api/v1/site-audit/start \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"country": "us", "domain": "example.com"}'
import requests
resp = requests.post(
"https://seonio.com/api/v1/site-audit/start",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"country": "us", "domain": "example.com"},
)
print(resp.json())
const resp = await fetch("https://seonio.com/api/v1/site-audit/start", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY",
},
body: JSON.stringify({"country": "us", "domain": "example.com"}),
});
console.log(await resp.json());
Run a real request
Send this request from your browser with your API key, or leave the key empty to see the sample response.
A successful run costs Free with a plan's monthly site audits, else $12. With no key, you see the sample response and nothing is charged.
{
"audit_id": "019a4f2e-7c31-7d02-a6b5-3e8f1c2d4a90",
"country": "us",
"domain": "example.com",
"eta_seconds": 300,
"free_audit": true,
"poll_after_seconds": 30,
"price": "$0",
"status": "queued",
"url": "https://seonio.com/site-audit/example.com?country=us"
}
What developers build with it
- Audit a client's site from your own tool.
- Check a site every month and track its Site Health.
The same contract on every endpoint
Error responses are JSON with a "detail" field. It is a message string unless the row above says otherwise.
| Code | When |
|---|---|
200 | Success. The lookup completed and was charged, even if the response is empty. /keywords/global charges only the keywords it looked up. |
401 | Missing or unknown API key. |
402 | Not enough balance. "detail" is an object with "error", "message", "balance_required" and "balance_available". Requests still running hold their price until they finish, so a retry can succeed once they do. |
403 | The account is not verified yet, or it is locked. |
409 | Another AI Visibility Report of this account is running, a start sent with free_only found no free report or site audit left, or the site was audited less than 30 days ago ("detail" is then an object with "error": "too_soon", "message", "audit_id" and "next_audit_at"); the detail says which. Not charged. |
422 | Invalid request (wrong shape or types, a keyword over 200 characters, a URL the page checker cannot audit, a domain that does not exist, or a bare public suffix such as co.uk that groups many websites) — never charged. "detail" is usually a list of validation errors; an answer that retrying cannot change (such as a domain without a DNS record) is a message string with an X-Outcome header naming it: missing, unsupported, too_large or refused_input. |
429 | Rate limit exceeded, never charged. Requests per second per account by plan: 5 on a free account, 10 on Starter, 15 on Pro and 20 on Business; retry after the Retry-After header. Also the page checker's provider limit and the AI Visibility Report's hourly limit on new reports. |
503 | A data provider failed or timed out (X-Outcome: temporary). Nothing was charged; retry after the seconds in the Retry-After header. |
Questions, answered
Simple answers for developers using the API.
Every endpoint has a published USD price or formula. Requests draw from the same testing, included and Extra Usage balance as website and MCP actions: testing first, then included usage, then Extra Usage expiring soonest.
API actions require a verified account with a free $1 balance or an active subscription balance. Create and manage API keys from your account, then send the key in the X-API-Key header.
Yes. Your account shows API usage and remaining balance, so you can track costs while building and running automated workflows.
REST API and MCP requests per second depend on your plan: 5 on a free account, 10 on Starter, 15 on Pro and 20 on Business. Website data requests from the same account count toward the same second. Requests above the limit return HTTP 429 with a Retry-After header and are not charged; wait a second and retry.
Turn search insights into measurable growth
Start your SEO research in seconds.