> ## 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.

# Runs

> List, read, stop and replay agent runs. Read the steps and snapshots of a run, and ask a follow-up in the same thread. Every run is kept for 24 hours.

Every [agent](https://docs.stophy.dev/agent/overview) run has an `id`. Use it to read the answer, follow the steps, stop the run, or ask a follow-up. All of these calls are free, and a run is kept for 24 hours.

## Read a run

Get an API key in the [Quickstart](https://docs.stophy.dev/quickstart). `GET /v1/agent/{id}` returns the state of a run.

```bash cURL theme={null}
curl https://api.stophy.dev/v1/agent/job_1U1n0vXaDokDUHZFMGj1rA \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```typescript TypeScript theme={null}
const response = await fetch("https://api.stophy.dev/v1/agent/job_1U1n0vXaDokDUHZFMGj1rA", {
  headers: { Authorization: `Bearer ${process.env.STOPHY_API_KEY}` },
});
const run = await response.json();
console.log(run.status, run.data, run.sources);
```

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

import requests

response = requests.get(
    "https://api.stophy.dev/v1/agent/job_1U1n0vXaDokDUHZFMGj1rA",
    headers={"Authorization": f"Bearer {os.environ['STOPHY_API_KEY']}"},
)
run = response.json()
print(run["status"], run["data"], run["sources"])
```

The response is in [Agent](https://docs.stophy.dev/agent/overview#read-the-response). These are its fields.

| Field | What it holds |
| - | - |
| `status` | `processing` while the run is queued or working, `completed` when it ended with an answer, `failed` when it ended without one or was stopped. |
| `queuePosition` | Where the run waits, while it is queued. |
| `data` | The fields the agent found. A field it did not find is left out. |
| `confidence` | For each field, a number from 0 to 1. |
| `sources` | For each field, the `url` and the exact `quote` it came from. Left out with `includeSources: false`. |
| `stoppedBy` | Why the run ended: `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` | What the run did: `n`, `action`, `detail` and `costUsd` for each step. |
| `skipped` | Pages the run could not read, each with an `error` and a `url`. |
| `model`, `mode`, `effort` | What the run used. |
| `threadId`, `threadTurn` | The thread of the run and the turn of the run in it. |
| `costUsd` | What the run has cost so far. |
| `createdAt`, `completedAt`, `expiresAt` | When the run started, when it ended and when it is deleted. |

## List runs

`GET /v1/agent` lists your runs from the last 24 hours, newest first, 20 to a page. Each row has the `id`, `createdAt`, `status`, `targetHint` and the `options` the run started with.

```bash theme={null}
curl https://api.stophy.dev/v1/agent \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

This real response is cut to the first run of three.

```json theme={null}
{
  "success": true,
  "agents": [
    {
      "id": "job_u8CXI2icHrwCUpX-DP_5Cg",
      "createdAt": "2026-11-17T18:10:37.282Z",
      "status": "completed",
      "targetHint": "https://bun.com/docs/runtime/sqlite",
      "origin": "api",
      "options": {
        "urls": ["https://bun.com/docs/runtime/sqlite"],
        "prompt": "Which of those modes does a plain transaction use?",
        "schema": {
          "type": "object",
          "properties": {
            "module": { "type": "string" },
            "transactionModes": { "type": "array", "items": { "type": "string" } }
          }
        },
        "model": "spark-2",
        "effort": "low"
      }
    }
  ],
  "costUsd": 0,
  "requestId": "2c2e7178-7528-49ff-88af-dc927af2cdaf"
}
```

When more runs follow, `next` holds the address of the next page. Or send `before`, a time in unix milliseconds, and read runs made before it. `limit` is 1 to 20.

## Stop a run

`DELETE /v1/agent/{id}` stops a run that is still working and keeps what it has read. What it spent is charged. The answer has `status` of `cancelled`.

```bash theme={null}
curl -X DELETE https://api.stophy.dev/v1/agent/job_1U1n0vXaDokDUHZFMGj1rA \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

A run that already ended cannot be stopped. This real answer came from a run that had finished, with HTTP status `409`.

```json theme={null}
{
  "retryable": false,
  "requestId": "35660548-bae0-4170-972e-bbf2cbd30c47",
  "success": false,
  "error": "This agent run already finished, so there is nothing to cancel. Read its pages with GET /v1/agent/job_1U1n0vXaDokDUHZFMGj1rA.",
  "code": "jobFinished"
}
```

## Read the trace

`GET /v1/agent/{id}/trace` returns every step of a run, in order, as events: when the run started, each step with what it cost, a snapshot of the answer after each round, the final answer, and when the run finished. A page the run could not read is an `error.occurred` event.

```bash theme={null}
curl https://api.stophy.dev/v1/agent/job_1U1n0vXaDokDUHZFMGj1rA/trace \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

This real response is cut to four of its eight events.

```json theme={null}
{
  "success": true,
  "id": "job_1U1n0vXaDokDUHZFMGj1rA",
  "events": [
    {
      "schemaVersion": 1,
      "eventId": "9df57ba1-be45-5127-989e-861cacb2a00a",
      "runId": "job_1U1n0vXaDokDUHZFMGj1rA",
      "occurredAt": "2026-11-17T18:10:05.379Z",
      "producerSequence": 0,
      "agent": { "id": "system", "role": "system", "name": "stophy" },
      "type": "run.started"
    },
    {
      "schemaVersion": 1,
      "eventId": "3c9e7b67-a18e-582f-82ee-b90a273bfe54",
      "runId": "job_1U1n0vXaDokDUHZFMGj1rA",
      "occurredAt": "2026-11-17T18:10:07.271Z",
      "producerSequence": 2,
      "agent": { "id": "agent", "role": "orchestrator", "name": "stophy-agent" },
      "n": 1,
      "stepType": "step",
      "action": "open",
      "detail": "read the page",
      "snapshotId": null,
      "type": "tool_call.finished",
      "toolCallId": "job_1U1n0vXaDokDUHZFMGj1rA:1",
      "toolName": "open",
      "result": { "costUsd": 0.001 }
    },
    {
      "schemaVersion": 1,
      "eventId": "1f8733a1-fdcd-5ea5-9577-7d27fbc2ce03",
      "runId": "job_1U1n0vXaDokDUHZFMGj1rA",
      "occurredAt": "2026-11-17T18:10:08.566Z",
      "producerSequence": 5,
      "agent": { "id": "agent", "role": "orchestrator", "name": "stophy-agent" },
      "n": 3,
      "stepType": "snapshot",
      "action": "snapshot",
      "detail": "after round 1",
      "snapshotId": "round-1",
      "type": "artifact.updated",
      "artifact": { "kind": "json", "artifactId": "answer", "snapshotId": "round-1", "change": "update" }
    },
    {
      "schemaVersion": 1,
      "eventId": "475e41c0-cde2-5b14-a0fa-022ba3e99e36",
      "runId": "job_1U1n0vXaDokDUHZFMGj1rA",
      "occurredAt": "2026-11-17T18:10:08.567Z",
      "producerSequence": 7,
      "agent": { "id": "system", "role": "system", "name": "stophy" },
      "type": "run.finished",
      "outcome": "succeeded",
      "error": null
    }
  ],
  "costUsd": 0.004,
  "requestId": "3f5cefcb-aefd-4382-864f-3a413faef74a"
}
```

A tool step has a `tool_call.started` event and a `tool_call.finished` event, and `result.costUsd` is what the step cost. `stepType` is `step`, `snapshot` or `answer`. The `outcome` of `run.finished` is `succeeded`, `failed`, `cancelled` or `credit_limit_reached`.

## Read a snapshot

A run takes up to three rounds, and the trace has a snapshot after each: its `snapshotId` is `round-1`, `round-2` and so on. `GET /v1/agent/{id}/snapshots/{snapshotId}` returns the answer the run had at that point. Use it to see how the answer grew, or to keep an earlier round.

```bash theme={null}
curl https://api.stophy.dev/v1/agent/job_1U1n0vXaDokDUHZFMGj1rA/snapshots/round-1 \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

```json theme={null}
{
  "success": true,
  "id": "job_1U1n0vXaDokDUHZFMGj1rA",
  "snapshotId": "round-1",
  "snapshot": "{\"data\":{\"module\":\"bun:sqlite\"},\"confidence\":{\"module\":0.9388}}",
  "snapshotData": {
    "data": { "module": "bun:sqlite" },
    "confidence": { "module": 0.9388 }
  },
  "costUsd": 0,
  "requestId": "73863efc-61f7-4425-bc68-b0ecea15d640"
}
```

`snapshot` is the answer as a JSON string, and `snapshotData` is the same answer as an object.

## Ask a follow-up

Send `threadId` with a new `prompt` to ask in the same thread. The run sees your earlier question and answer, and `urls`, `schema`, `effort`, `mode`, `location` and `safe` carry over unless you send new ones. With `"mode": "chat"`, a follow-up that needs no new data gets a short reply in `message`, for \$3 per 1,000 pages, and a follow-up that needs more reads the pages again.

```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 of those modes does a plain transaction use?",
    "threadId": "job_1U1n0vXaDokDUHZFMGj1rA",
    "mode": "chat",
    "maxCredits": 25
  }'
```

```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 of those modes does a plain transaction use?",
    threadId: "job_1U1n0vXaDokDUHZFMGj1rA",
    mode: "chat",
    maxCredits: 25,
  }),
});
const followUp = await response.json();
console.log(followUp.id, followUp.threadTurn);
```

```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 of those modes does a plain transaction use?",
        "threadId": "job_1U1n0vXaDokDUHZFMGj1rA",
        "mode": "chat",
        "maxCredits": 25,
    },
)
follow_up = response.json()
print(follow_up["id"], follow_up["threadTurn"])
```

The follow-up is a new run with its own `id`. It keeps the `threadId` and has `threadTurn` of 2.

```json theme={null}
{
  "success": true,
  "id": "job_u8CXI2icHrwCUpX-DP_5Cg",
  "url": "https://api.stophy.dev/v1/agent/job_u8CXI2icHrwCUpX-DP_5Cg",
  "threadId": "job_1U1n0vXaDokDUHZFMGj1rA",
  "threadTurn": 2,
  "costUsd": 0,
  "requestId": "7cf70786-b777-49ac-809e-2c3ab4f8b0d1"
}
```

In this run the first step was `chat`, which tried to answer from the earlier answer at no cost. The earlier answer did not hold the modes, so the run read the page again and charged \$0.004.

## Read a thread

`GET /v1/agent/threads/{threadId}` returns every turn of a thread, oldest first. Add `includeData=true` to get the `data` of each finished run.

```bash theme={null}
curl "https://api.stophy.dev/v1/agent/threads/job_1U1n0vXaDokDUHZFMGj1rA?includeData=true" \
  -H "Authorization: Bearer $STOPHY_API_KEY"
```

This real response is cut to the second turn.

```json theme={null}
{
  "success": true,
  "thread": {
    "id": "job_1U1n0vXaDokDUHZFMGj1rA",
    "createdAt": "2026-11-17T18:10:05.379Z",
    "updatedAt": "2026-11-17T18:10:41.817Z",
    "status": "idle",
    "runs": [
      {
        "id": "job_u8CXI2icHrwCUpX-DP_5Cg",
        "turn": 2,
        "mode": "chat",
        "prompt": "Which of those modes does a plain transaction use?",
        "urls": ["https://bun.com/docs/runtime/sqlite"],
        "schema": {
          "type": "object",
          "properties": {
            "module": { "type": "string" },
            "transactionModes": { "type": "array", "items": { "type": "string" } }
          }
        },
        "effort": "low",
        "status": "succeeded",
        "createdAt": "2026-11-17T18:10:37.282Z",
        "finishedAt": "2026-11-17T18:10:41.817Z",
        "costUsd": 0.004,
        "data": { "module": "bun:sqlite" }
      }
    ]
  },
  "costUsd": 0,
  "requestId": "e8912ff8-6efa-4997-bb8d-5b880065670a"
}
```

The `status` of a thread is `running` while a turn works and `idle` otherwise. A run's `status` is `processing`, `succeeded`, `failed`, `cancelled` or `credit_limit_reached`.

## Options

| Field | Where | Effect |
| - | - | - |
| `before` | `GET /v1/agent` | Only runs made before this time, in unix milliseconds. |
| `limit` | `GET /v1/agent` | How many runs, 1 to 20. The default is 20. |
| `includeData` | thread | `true` adds the `data` of each finished run. |
| `threadId` | `POST /v1/agent` | Ask a follow-up in this thread. |
| `mode` | `POST /v1/agent` | `chat` replies from the earlier answer when it can. |
| `maxTextLength` | every read | A query parameter. Cuts every text value in the response to this many characters. |

## Limits and errors

* Runs, threads, traces and snapshots are kept for 24 hours. An unknown run returns `404 notFound`. An unknown thread returns `404 notFound` with `No agent thread with that id. Threads are kept for 24 hours.` An unknown snapshot returns `404 notFound` with `No snapshot with that id for this run.`
* `DELETE` on a run that already ended returns `409 jobFinished`.
* `zeroDataRetention` cannot be sent with `threadId`: a thread keeps what it has said.
* `strictConstrainToURLs` with no `urls`, and no thread that has them, returns `400 invalidRequest`.
* You can read only your own runs.

## Related

* [Agent](https://docs.stophy.dev/agent/overview) starts a run and sets its cap.
* [Webhooks](https://docs.stophy.dev/webhooks.md) pushes `started`, `page`, `action`, `completed`, `failed` and `cancelled` events.
* [Extract](https://docs.stophy.dev/extract/overview) fills fields from pages you name, in one call.
* [Usage and logs](https://docs.stophy.dev/production/usage-and-logs.md) shows what each call cost.


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