Go from zero to your first captured AI answer — as JSON — in about five minutes.
Query a real consumer AI search engine and get the answer users actually see — plus the structured evidence behind it — as JSON. This guide gets you from an API key to a parsed Envelope in about five minutes.
1
Get an API key
Grab a key from the dashboard, then export it so the examples below just work.
Open the dashboard and go to Settings → API Keys.
Create a key and copy it (you only see the full value once).
Export it in your shell:
export AISEARCH_API_KEY="sk_live_..."
Verify connectivity with the unauthenticated health check:
curl https://api.aisearchapi.dev/v1/health
Response
{ "status": "ok", "schemaVersion": "1.0" }
New accounts start with 500 free credits, no card required. A capture is charged only on success — an empty or failed capture costs nothing. See pricing.
2
Make your first search
Submit a query and at least one surface. By default the API is async: it returns 202 immediately with a parent job and one child per surface × region.
The response carries a Location header pointing at the parent job. Each entry in children is a child id — a dotted id (job_8t2q.chatgpt.us) that resolves to the Envelope for one surface in one region.
3
Poll for the result
Fetch a job with GET /v1/jobs/:id. A child id (dotted) returns the canonical Envelope. Poll until the job reaches any terminal state — completed, partial, failed, canceled, or expired — and never past it.
Polling is fine for a single surface. For fan-out across many surfaces and regions, prefer webhooks — you get a POST on each child’s terminal state instead of polling N jobs.
4
Read the Envelope
A completed child returns four sections: job, provenance, answer, and evidence.
The same answer with formatting; always populated.
answer.blocks[].referenceIds
Which evidence.sources each block cites.
evidence.sources[]
Every source, each with a role (cited / retrieved / related), a cited flag, and charRanges mapping it back into the answer.
evidence.fanOut.queries
The follow-up queries the surface ran under the hood.
evidence.mentions
Brands and entities named in the answer.
provenance.model
Which model produced it, whether it was inferred, and a confidence score.
provenance.surfacePresent
false means the surface returned nothing (see below).
When a surface returns nothing, the job still reaches completed with provenance.surfacePresent: false, an empty answer, and a surface_absent entry in job.warnings. Absence is a valid, billable-free result — the capture costs no credits.
Sync mode resolves one surface at a time. For more than one surface — or when you hit CONCURRENCY_LIMIT_EXCEEDED — use the default async flow with polling or webhooks.
