Skip to content

Search Seonio

Type a keyword, domain, or paste a URL

Start free with $1 to see full results. Powered by Seonio
SEO API

AI Visibility Report

Does AI recommend this brand? Four engines, 10 buyer questions.

POST /api/v1/ai-visibility/report$10 / reportAuth: X-API-Key header
seonio / rest apiFrom the API docs
RequestPOST /api/v1/ai-visibility/report
curl -X POST https://seonio.com/api/v1/ai-visibility/report \
  -H "Content-Type: application/json" \
  -H "X-API-Key: $SEONIO_API_KEY" \
  -d '{"country": "us", "domain": "example.com"}'
Response200 OK
{
  "report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15",
  "page": null,
  "status": "queued",
  "url": "https://seonio.com/ai-visibility/01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15",
  "free_report": false,
  "eta_seconds": 275,
  "poll_after_seconds": 20
}
Contract

What to send and what comes back

Step 1: start the standard report for a domain (or page URL): 10 buyer questions written for it, never naming the brand (from the page, when `domain` is a page URL; outside the US in the country's language, naming the country), asked to ChatGPT, Google AI Overviews, Gemini and Perplexity. $10 is taken from the balance once the questions are written and kept when the report is delivered. If fewer than half of the answers arrive, or fewer than 3 engines answer, the charge is refunded automatically. While you still have a free report this month (free_reports_left above 0), the report uses it instead and nothing is charged. If fewer than half of the answers arrive, or fewer than 3 engines answer, you get the free report back to use before your plan month ends. One report at a time per account: until a report ends, a repeat call for the same domain (or page) and country returns it without a second charge (safe to retry after a timeout). Once it has ended, a new call starts a new report and is charged again. Another domain, page or country while one runs is a 409 naming the running report_id, and so is free_only with no free report left. A domain without a DNS record, a homepage or page that could not be read, or a site no questions could be written for is a 422; too many new reports in an hour is a 429; questions that took too long to write are a 503 with Retry-After. None of these is charged. 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

Request body
FieldTypeRequiredDescription
domain string required A domain or a page URL: the brand's website, e.g. example.com (a subdomain is reported as its main domain), or a product or category page, e.g. example.com/product (the report is then about that page's product: its questions are written from the page and the site checks run on it; the brand is still counted by its domain). Tracking parameters (utm_*) are dropped; at most 500 characters, no file URL. A bare public suffix such as co.uk is refused.
country string optional The market the four engines are asked from, in its language (default "us"; "uk" is accepted and returned as "gb").
50 supported countries
dzAlgeriaarArgentinaauAustraliaatAustriabdBangladeshbeBelgiumbrBrazilbgBulgariacaCanadaczCzechiadkDenmarkegEgyptfiFinlandfrFrancedeGermanyghGhanagrGreecehuHungaryinIndiaidIndonesiaieIrelanditItalyjpJapankeKenyamyMalaysiamxMexicomaMorocconlNetherlandsnzNew ZealandngNigerianoNorwaypkPakistanphPhilippinesplPolandptPortugalroRomaniasaSaudi ArabiarsSerbiasgSingaporezaSouth AfricaesSpainlkSri LankaseSwedenchSwitzerlandthThailandtrTurkiyeaeUnited Arab EmiratesgbUnited Kingdom (also uk, returned as gb)usUnited StatesvnVietnam
free_only boolean optional Optional, default false. True starts the report only as one of your free reports: when none is left, the call is a 409 and nothing is charged (send it when your user approved a free report, so it never becomes a $10 charge).

Response

Response fields
FieldTypeDescription
report_id string The report's id.
page string | null The page URL the report is about, when `domain` was a page URL; null for a domain.
status string "queued" or "running" (then "finishing", "done" or "failed").
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).
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.
Code

Copy, paste, add your key

The same request in cURL, Python and Node.js.

cURL
curl -X POST https://seonio.com/api/v1/ai-visibility/report \
  -H "Content-Type: application/json" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"country": "us", "domain": "example.com"}'
Python
import requests

resp = requests.post(
    "https://seonio.com/api/v1/ai-visibility/report",
    headers={"X-API-Key": "YOUR_API_KEY"},
    json={"country": "us", "domain": "example.com"},
)
print(resp.json())
Node.js
const resp = await fetch("https://seonio.com/api/v1/ai-visibility/report", {
  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());
Playground

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 $10 / report. With no key, you see the sample response and nothing is charged.

POST /api/v1/ai-visibility/reportSample response
{
  "eta_seconds": 275,
  "free_report": false,
  "page": null,
  "poll_after_seconds": 20,
  "report_id": "01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15",
  "status": "queued",
  "url": "https://seonio.com/ai-visibility/01929a7e-5b2c-7c11-9d3e-2f6a8b4c0e15"
}
Use cases

What developers build with it

  • AI search (GEO) audits for a brand.
  • Tracking how AI assistants recommend competitors.
Status codes

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.

Status codes
CodeWhen
200Success. The lookup completed and was charged, even if the response is empty. /keywords/global charges only the keywords it looked up.
401Missing or unknown API key.
402Not 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.
403The account is not verified yet, or it is locked.
409Another 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.
422Invalid 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.
429Rate 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.
503A data provider failed or timed out (X-Outcome: temporary). Nothing was charged; retry after the seconds in the Retry-After header.
FAQ

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.

Free $1 to test · No card required

Turn search insights into measurable growth

Start your SEO research in seconds.

SEO researchREST APIMCP