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

# titan_get_run

> Poll status and retrieve results for any Titan MCP run, with pagination across large result sets.

Call `titan_get_run` whenever a tool returns `queued` or `running`, and to page through results too large for a single response. It reads state only—it never starts new work and never consumes credits.

**Required scope:** `mcp:runs:read`

## Parameters

<ParamField body="run_id" type="string" required>
  The `run_id` returned by `titan_search`, `titan_fetch`, `titan_crawl`, or `titan_run_template`. Must be a UUID—this is the Titan `execution_id`.
</ParamField>

<ParamField body="include_results" type="boolean" default="true">
  Include result records. Set `false` for a lightweight status check while a long run is in flight.
</ParamField>

<ParamField body="result_format" type="string">
  Requested shape for returned records.
</ParamField>

<ParamField body="limit" type="integer" default="100">
  Records per page, up to 1000.
</ParamField>

<ParamField body="offset" type="integer" default="0">
  Records to skip. Combine with `limit` to paginate.
</ParamField>

## Example

```json theme={null}
{
  "run_id": "7b2e4f18-9c53-4a06-b1d7-8e2f5a9c3b41",
  "limit": 100,
  "offset": 0
}
```

## Response

```json theme={null}
{
  "run_id": "7b2e4f18-9c53-4a06-b1d7-8e2f5a9c3b41",
  "status": "completed",
  "progress": 100,
  "steps": [
    {
      "step_id": "step-1",
      "status": "completed",
      "expected_count": 42,
      "processed_count": 42
    }
  ],
  "results": [
    { "url": "https://example.com/docs/api/authentication", "title": "Authentication", "depth": 1 }
  ],
  "datasets": {},
  "usage": {
    "backend_execution_id": "7b2e4f18-9c53-4a06-b1d7-8e2f5a9c3b41",
    "billing_unit": "successful_delivery",
    "records_returned": 42,
    "records_available": 42,
    "billing_status": "billable"
  },
  "warnings": [],
  "request_id": "req_1f7a3c9e5b2d8064"
}
```

### Response fields

| Field      | Meaning                                                               |
| ---------- | --------------------------------------------------------------------- |
| `status`   | `completed`, `partial`, `running`, `queued`, `failed`, or `cancelled` |
| `progress` | Percentage complete, 0 to 100                                         |
| `steps`    | Per-step state, useful for watching multi-step runs advance           |
| `results`  | Result records, present only once the run reaches a terminal status   |
| `datasets` | Dataset references when the run produced exportable data              |
| `usage`    | Record counts and billing status                                      |

<Note>
  `results` is populated only for terminal runs. While a run is `queued` or `running`, use `progress` and `steps` to report advancement rather than waiting for partial records.
</Note>

## Polling

Poll with backoff rather than in a tight loop. Every call is a real request, and hammering it will not make the run finish sooner.

| Elapsed                 | Suggested interval  |
| ----------------------- | ------------------- |
| First 30 seconds        | Every 2–3 seconds   |
| 30 seconds to 2 minutes | Every 5–10 seconds  |
| Beyond 2 minutes        | Every 15–30 seconds |

Set `include_results: false` while polling and switch it on once the status is terminal—that keeps each poll small.

```mermaid theme={null}
flowchart LR
    A[Tool returns run_id] --> B[titan_get_run]
    B --> C{Terminal?}
    C -->|No| D[Wait, back off]
    D --> B
    C -->|Yes| E[Read results]
```

## Pagination

Results aggregate across all steps of a run, in step order. Page through them with `limit` and `offset`:

```json theme={null}
{ "run_id": "7b2e4f18-9c53-4a06-b1d7-8e2f5a9c3b41", "limit": 100, "offset": 0 }
{ "run_id": "7b2e4f18-9c53-4a06-b1d7-8e2f5a9c3b41", "limit": 100, "offset": 100 }
{ "run_id": "7b2e4f18-9c53-4a06-b1d7-8e2f5a9c3b41", "limit": 100, "offset": 200 }
```

Compare `records_returned` against `records_available` in `usage` to know when you have read everything.

## Warnings you may see

| Code                | Meaning                                                                 |
| ------------------- | ----------------------------------------------------------------------- |
| `steps_unavailable` | Step data could not be loaded, so results were omitted. Retry the call. |

`steps_unavailable` exists so an agent can distinguish "this run produced nothing" from "results could not be loaded right now". Treat it as retryable, never as an empty result.

## Ownership

You can only read runs owned by the same Titan user as your API key. An unknown or out-of-scope `run_id` returns a not-found error rather than someone else's data.

## Using the run elsewhere

`run_id` is the Titan `execution_id`, so the same identifier works across the platform:

* `GET /api/v1/executions/{run_id}` — full execution detail
* `GET /api/v1/executions/{run_id}/results/export` — export the complete result set
* Analytics and billing endpoints accept it as `execution_id`

See [Monitor and control executions](/docs/use-the-platform/monitor-and-control-executions).

## Next steps

* [Runs and results](/docs/mcp/runs-and-results) — the full lifecycle
* [titan\_crawl](/docs/mcp/tools/titan-crawl) — the tool that most often needs polling