> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stophy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent

> Give a task in plain words and the agent searches, reads pages and fills your fields, with the quote behind each value. You set the most a run may spend.

Agent finds the pages for you. If you already know the pages, use [Extract](https://docs.stophy.dev/extract/overview). It answers at once with an `id`, and you read the answer with `GET /v1/agent/{id}`. It needs an API key. See the [Quickstart](https://docs.stophy.dev/quickstart.md).

```bash cURL theme={null}
curl -X POST https://api.stophy.dev/v1/agent \
  -H "Authorization: Bearer $STOPHY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Which module do I import to use SQLite in Bun, and which transaction modes does it support?",
    "urls": ["https://bun.com/docs/runtime/sqlite"],
    "schema": {
      "type": "object",
      "properties": {
        "module": { "type": "string" },
        "transactionModes": { "type": "array", "items": { "type": "string" } }
      }
    },
    "effort": "low",
    "strictConstrainToURLs": true,
    "maxCredits": 50
  }'
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/agent", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.STOPHY_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    prompt:
      "Which module do I import to use SQLite in Bun, and which transaction modes does it support?",
    urls: ["https://bun.com/docs/runtime/sqlite"],
    schema: {
      type: "object",
      properties: {
        module: { type: "string" },
        transactionModes: { type: "array", items: { type: "string" } },
      },
    },
    effort: "low",
    strictConstrainToURLs: true,
    maxCredits: 50,
  }),
});
const { id } = await response.json();
```

```python Python theme={null}
import os

import requests

response = requests.post(
    "https://api.stophy.dev/v1/agent",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
    json={
        "prompt": "Which module do I import to use SQLite in Bun, and which transaction modes does it support?",
        "urls": ["https://bun.com/docs/runtime/sqlite"],
        "schema": {
            "type": "object",
            "properties": {
                "module": {"type": "string"},
                "transactionModes": {"type": "array", "items": {"type": "string"}},
            },
        },
        "effort": "low",
        "strictConstrainToURLs": True,
        "maxCredits": 50,
    },
)
run_id = response.json()["id"]
```

The start call is free and returns `id`, `url`, `threadId` and `threadTurn` (1 for a first question). Poll `GET /v1/agent/{id}` every few seconds while `status` is `processing`:

```json theme={null}
{
  "success": true,
  "status": "completed",
  "data": { "module": "bun:sqlite" },
  "sources": {
    "module": {
      "url": "https://bun.com/docs/runtime/sqlite",
      "quote": "To use it, import from the built-in bun:sqlite module."
    }
  },
  "stoppedBy": "done",
  "expiresAt": "2026-11-18T18:10:05.379Z"
}
```

`transactionModes` is missing: the agent did not find it in one round, so the field is left out.

## Run fields

| Field | Holds |
| - | - |
| `status` | `processing` while queued or working, `completed` with an answer, `failed` without one or when stopped. |
| `queuePosition` | Where the run waits, while queued. |
| `data`, `confidence` | The fields found, and 0 to 1 for each. A field not found is left out. A completed run with nothing found has an empty `data`. |
| `sources` | For each field, the `url` and the exact `quote`. Absent with `includeSources: false`. |
| `stoppedBy` | `done`, `rounds` or `maxCredits`. |
| `stopReason`, `partial`, `partialSchemaValid` | With `credit_limit_reached`: what the run found before the cap, and whether it fills your schema. |
| `message` | The reply to a `chat` follow-up. |
| `error` | Why a run failed. |
| `steps` | Each step: `n`, `action`, `detail`, `costUsd`. |
| `skipped` | Pages the run could not read, each with `url` and `error`. |
| `model`, `mode`, `effort` | What the run used. |
| `threadId`, `threadTurn` | The thread and the turn in it. |
| `costUsd` | The cost so far. |
| `createdAt`, `completedAt`, `expiresAt` | Run times. |

## Request fields

| Field | Default | Effect |
| - | - | - |
| `prompt` | none | Required. What to find, 1 to 10,000 characters. |
| `schema` | none | The fields to fill, as a JSON Schema. Up to 100 top-level fields and 32 KB. Keywords are on [Extract](https://docs.stophy.dev/extract/overview#schema). |
| `urls` | none | Up to 20 start pages. An address with `*`, such as `https://qdrant.tech/blog/*`, expands from the site's page list to at most 10 pages. With no `urls` the agent searches the web. |
| `effort` | `high` | Search-and-read rounds: `low` 1, `medium` 2, `high` 3. |
| `maxCredits` | `2500` | The most the run may spend, in steps. See [Pricing](https://docs.stophy.dev/account/pricing.md). |
| `strictConstrainToURLs` | `false` | Read only the pages in `urls`, in one round, with no searching. Needs `urls`, or a thread that has them. |
| `mode` | `extract` | `chat` lets a follow-up that needs no new data get a short reply in `message`. Needs `threadId`. |
| `threadId` | none | Ask a follow-up in the same thread. |
| `includeSources` | `true` | Send `false` to leave `sources` out. |
| `location` | none | `{ "country": "DE" }` searches and reads as from that country. |
| `safe` | `false` | Hide explicit results from the run's web searches. Pages in `urls` and pages the agent opens are not filtered. |
| `model` | `stophy` | Any name up to 100 characters. Every name runs the same agent, and the name comes back. |
| `zeroDataRetention` | `false` | Keep nothing, held 1 hour at most. Not with `threadId`. See [Zero data retention](https://docs.stophy.dev/production/zero-data-retention.md). |
| `auditMetadata` | none | `{ "username": "..." }`, kept with the run and returned by the status call. |
| `webhook` | none | Events `started`, `page`, `action`, `completed`, `failed`, `cancelled`. See [Webhooks](https://docs.stophy.dev/webhooks.md). |

## Cap what a run spends

Every step is checked against what is left before it runs, so a run never goes over `maxCredits`, and what it spent before it stopped is charged. A run that cannot answer inside the cap ends with `status: "failed"`, `stopReason: "credit_limit_reached"` and what it found in `partial`. If the cap cannot cover the first step, `steps` is empty and the run is free. For price, see [Pricing](https://docs.stophy.dev/account/pricing.md).

## Follow up in a thread

Send `threadId` with a new `prompt` to `POST /v1/agent`. The run sees your earlier question and answer. `urls`, `schema`, `effort`, `mode`, `location` and `safe` carry over unless you send new ones. A follow-up is a new run with its own `id`, the same `threadId` and the next `threadTurn`. With `"mode": "chat"`, a follow-up the earlier answer cannot support reads the pages again.

`GET /v1/agent/threads/{threadId}` returns every turn, oldest first, with inputs, times and `costUsd`. Add `includeData=true` for each finished run's `data`. A thread `status` is `running` or `idle`. A run's `status` there is `processing`, `succeeded`, `failed`, `cancelled` or `credit_limit_reached`.

## Manage runs

| Call | Does |
| - | - |
| `GET /v1/agent` | Lists runs from the last 24 hours, newest first. `limit` 1 to 20 (default 20), `before` in unix milliseconds, and `next` for the next page. Rows have `id`, `createdAt`, `status`, `targetHint`, `options`, `origin`, under `agents`. |
| `DELETE /v1/agent/{id}` | Stops a working run, keeps what it read, and charges what it spent. The answer has `status: "cancelled"`. A run that already ended returns `409 jobFinished`. |
| `GET /v1/agent/{id}/trace` | Every step in order as `events`. Order them by `producerSequence`. A tool step has `tool_call.started` and `tool_call.finished`, with `result.costUsd`. A page it could not read is `error.occurred`. `run.finished` has an `outcome`: `succeeded`, `failed`, `cancelled` or `credit_limit_reached`. |
| `GET /v1/agent/{id}/snapshots/{snapshotId}` | The answer after a round, with `snapshotId` `round-1`, `round-2`, `round-3`. `snapshotData` is the object, `snapshot` the same as a JSON string. |

Every read takes `maxTextLength`, a query parameter that cuts each text value in the response to that many characters.

## Limits and errors

Codes are on [Errors](https://docs.stophy.dev/api-reference/errors.md).

* Runs, threads, traces and snapshots are kept for 24 hours. After that, `404 notFound`. You can read only your own.
* `400 invalidRequest`: `strictConstrainToURLs` with no `urls` and no thread that has them, or `zeroDataRetention` with `threadId`.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.