Overview
It researches rather than crawls. First it turns your objective into sub-questions and search queries, because an objective is rarely a good query. Then it reads. Then it looks at what it found, names what is still missing, and decides what to ask next — new searches, or a link it saw on a page it already read. That cycle repeats until the evidence meets the criteria it set for itself at the start, or until it runs out of envelope. The plan it wrote and the reasoning behind each round come back with the answer. Where sources disagree, you are told. A field backed by two independent pages carries two citations, one marked primary; a field two pages contradict each other on comes back inconflicts with both values and both quotes, rather than quietly resolved to whichever the model preferred. The disagreement is usually the most useful thing the research found.
Three tiers set the envelope: lite reads up to 3 sources and does not reason at all, standard reads up to 15 across 2 rounds, deep up to 100 across 6. The tier is a CEILING, not a price — you pay for one task, one unit per source actually read, and one per reasoning round, so a standard task answered from four pages after one round costs what that actually was. A budget can narrow any ceiling but never widen it; set maxRounds: 0 to skip reasoning entirely and just extract from what you supply.
It is cheap because of what it does not buy. A page costs one credit as markdown and five with the vendor’s own extraction; Superagent buys the one and extracts itself, then caches both the page and the extraction — so a re-run over a site that has not changed pays for almost none of it again. Polling and cancelling are never billed. A task that fails still bills the sources and rounds it really consumed, but not the task unit.
What it does not do: it is not synchronous, and wait: true is a 60-second convenience rather than a guarantee — if you need an answer inside one HTTP request, /v1/scrape is the right call. It does not log into anything, so pages behind an account are out of reach. It only follows links it actually saw on pages it read, never a URL it invented. And it will not fill your schema to look complete: a field no source supports comes back missing, which is the honest answer and occasionally a surprising one.
Endpoints
POST /v1/superagent — Give it a research question and a JSON schema. It plans, searches, reads, notices what is missing, searches again — and cites every field.cost.units — the quantity you were metered for this call.
GET /v1/superagent/{taskId} — Poll a running task: status, partial output, sources read, spend so far. Not billed.
This API answers before the work is done
POST /v1/superagent returns 202 Accepted with an id, not a result. The response carries a Location header pointing at /v1/superagent/{taskId} and a Retry-After of 5 seconds — poll no faster than that. Send DELETE /v1/superagent/{taskId} to stop it.task.taskId in the create response. Polling and cancelling are never billed, so a loop that respects Retry-After costs nothing beyond the work itself.
Request headers
Request options
Pricing
Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see Billing.
Authentication
Send a key as a bearer token. This service’s operations require thetasks:run and tasks:read scopes, granted independently — and the project must have Superagent enabled. See Authentication.