AI Visibility Result
Progress and the finished AI Visibility Report, free.
curl -X POST https://seonio.com/api/v1/ai-visibility/result \ -H "Content-Type: application/json" \ -H "X-API-Key: $SEONIO_API_KEY" \ -d '{"report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15"}'
{
"report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15",
"domain": "example.com",
"page": null,
"country": "us",
"status": "running",
"stage": "answers",
"progress": {
"questions": 10,
"answers": {
"chatgpt": 7,
"overview": 10
},
"answers_of": 10
},
"eta_seconds": 190,
"poll_after_seconds": 20,
"error": null,
"created_at": "2026-10-20T14:02:11",
"finished_at": null,
"url": "https://seonio.com/ai-visibility/01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15",
"free_report": false,
"report": null
}What to send and what comes back
Step 2: where the report is and, once done, the report itself: the questions it asked, who the engines recommend, per question and engine, the pages they cite, and the ranked list of fixes. It never includes the engines' full answers (they are on the report's page), the run's working data or provider costs. Send report_id, or domain and country instead (not both) to get this account's newest report of them: the running one, else the last one that ended (for a client that lost the report_id). Only the account that started a report can read it: an id that is not one of this account's reports, or a domain and country it has no report of, is a 422. The report runs in the background, in two calls: 1. POST /api/v1/ai-visibility/report ($10) writes the buyer questions for a domain (or a page URL) and country, starts the standard report with them and returns a report_id; the call usually takes 10 to 20 seconds, up to about a minute. 2. POST /api/v1/ai-visibility/result (free) with that report_id, or with the same domain and country: poll every 15 to 30 seconds. A report typically takes 4 to 8 minutes, longer outside the US; eta_seconds (may be null) estimates the rest. It ends done, with the report and the questions it asked, or failed, refunded. To review or edit the questions before you pay, run the report on seonio.com.
Request body
| Field | Type | Required | Description |
|---|---|---|---|
report_id |
string | null | optional | The report_id the report call returned. |
domain |
string | null | optional | Instead of report_id: the domain or page URL the report was started for. |
country |
string | optional | With domain: the report's country (default "us"; "uk" is accepted as "gb").
50 supported countriesdzAlgeriaarArgentinaauAustraliaatAustriabdBangladeshbeBelgiumbrBrazilbgBulgariacaCanadaczCzechiadkDenmarkegEgyptfiFinlandfrFrancedeGermanyghGhanagrGreecehuHungaryinIndiaidIndonesiaieIrelanditItalyjpJapankeKenyamyMalaysiamxMexicomaMorocconlNetherlandsnzNew ZealandngNigerianoNorwaypkPakistanphPhilippinesplPolandptPortugalroRomaniasaSaudi ArabiarsSerbiasgSingaporezaSouth AfricaesSpainlkSri LankaseSwedenchSwitzerlandthThailandtrTurkiyeaeUnited Arab EmiratesgbUnited Kingdom (also uk, returned as gb)usUnited StatesvnVietnam |
Response
| Field | Type | Description |
|---|---|---|
report_id |
string | The report's id. |
domain |
string | null | The domain (a page report's main domain). |
page |
string | null | The page URL the report is about, when `domain` was a page URL; null for a domain. |
country |
string | null | The market's ISO code. |
status |
string | "queued", "running", "finishing", "done" or "failed". |
stage |
string | null | The step it is on while it runs. |
progress |
object | Counts so far: answers per engine, reads, pages. |
eta_seconds |
integer | null | Estimated seconds left while it runs (an estimate, not a promise); null when there is no estimate yet; 0 once ended. |
poll_after_seconds |
integer | null | When to call again; null once there is nothing to wait for. |
error |
string | null | Why a failed report failed; a failed report is not charged. |
created_at |
string | null | When it started (UTC). |
finished_at |
string | null | When it ended (UTC). |
url |
string | The report's page on seonio.com (signed in to this account). |
free_report |
boolean | True when the report used one of your free reports left this month (nothing charged). |
report |
object | null | The finished report once done, else null. |
Copy, paste, add your key
The same request in cURL, Python and Node.js.
curl -X POST https://seonio.com/api/v1/ai-visibility/result \
-H "Content-Type: application/json" \
-H "X-API-Key: YOUR_API_KEY" \
-d '{"report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15"}'
import requests
resp = requests.post(
"https://seonio.com/api/v1/ai-visibility/result",
headers={"X-API-Key": "YOUR_API_KEY"},
json={"report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15"},
)
print(resp.json())
const resp = await fetch("https://seonio.com/api/v1/ai-visibility/result", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "YOUR_API_KEY",
},
body: JSON.stringify({"report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15"}),
});
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 $0 / request. With no key, you see the sample response and nothing is charged.
{
"country": "us",
"created_at": "2026-10-20T14:02:11",
"domain": "example.com",
"error": null,
"eta_seconds": 190,
"finished_at": null,
"free_report": false,
"page": null,
"poll_after_seconds": 20,
"progress": {
"answers": {
"chatgpt": 7,
"overview": 10
},
"answers_of": 10,
"questions": 10
},
"report": null,
"report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15",
"stage": "answers",
"status": "running",
"url": "https://seonio.com/ai-visibility/01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15"
}
What developers build with it
- Poll a running report.
- Read the finished report as JSON.
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, or a start sent with free_only found no free report or site audit left; 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.