# Superagent

> Give it a research question and a JSON schema. It plans, searches, reads, notices what is missing, searches again — and cites every field.

Source: https://cloud.gomry.com/services/tasks

Superagent is the one API here whose work outlives your request. POST a research question and a JSON schema and you get a task id back immediately; it then works for minutes or hours, and you collect the result by polling or by webhook. Every field in the output names the URL it came from and quotes the sentence that supports it — a field we cannot cite is dropped rather than guessed.

## 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 in `conflicts` 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.

```bash
curl -X POST https://api.cloud.gomry.com/v1/superagent \
  -H "Authorization: Bearer $GOMRY_CLOUD_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "objective": "Which of these venues changed their refund policy in 2026, and how?",
    "seedUrls": ["https://example.com/venue/calendar"],
    "outputSchema": { "type": "object", "properties": {
      "shows": { "type": "array", "items": { "type": "object", "properties": {
        "name": { "type": "string" }, "startDate": { "type": "string" } } } } } },
    "tier": "standard"
  }'
```

The response reports `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.

```bash
curl -X GET https://api.cloud.gomry.com/v1/superagent/{taskId} \
  -H "Authorization: Bearer $GOMRY_CLOUD_KEY"
```

This operation is not billed.

**DELETE /v1/superagent/{taskId}** — Stop a task admitting further steps. Not billed, and never refunds work already done.

```bash
curl -X DELETE https://api.cloud.gomry.com/v1/superagent/{taskId} \
  -H "Authorization: Bearer $GOMRY_CLOUD_KEY"
```

This operation is not billed.

## This API answers before the work is done

> **Note:** `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.

The id is at `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

- `Idempotency-Key` — Two requests carrying the same key on one project return the same task instead of starting a second. Send one whenever a retry is possible — an unattended caller that retries without it pays twice for the same research.

## Request options

- `objective` — Required. 1–2000 characters describing what you want found, in plain language.
- `outputSchema` — Required. A JSON Schema object describing the shape you want back. Returned in `output`, with a matching entry in `citations` for every field.
- `seedUrls` — URLs to start from, up to 100 and never more than the tier's source ceiling. Omit and the task searches for its own sources. Private addresses and internal hostnames are refused at creation.
- `tier` — lite | standard | deep. Sets the source, round, cost and time ceilings. Defaults to standard.
- `budget` — { maxCostMicroUsd, maxSources, deadlineSeconds, maxRounds }. Each is intersected with the tier's ceiling — it can only narrow. `maxRounds: 0` is honoured as "do not reason, just read what I gave you".
- `webhookUrl` — Called once when the task reaches a terminal state. Must be a public host.
- `wait` — Block up to 60s for a terminal state before responding. The task is unaffected and keeps running if the wait expires. Defaults to false.

## Pricing

| Unit | Price |
| --- | --- |
| per task | $0.03 |
| per source | 0.7¢ |
| per round | 0.8¢ |

Only calls that returned a result are billed. Failures cost nothing. Billed monthly in arrears — see [Billing](https://cloud.gomry.com/docs/billing).

## Authentication

Send a key as a bearer token. This service's operations require the `tasks:run` and `tasks:read` scopes, granted independently — and the project must have Superagent enabled. See [Authentication](https://cloud.gomry.com/docs/authentication).