titan_get_run

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

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.

boolean

default:"true"

Include result records. Set false for a lightweight status check while a long run is in flight.

string

Requested shape for returned records.

integer

default:"100"

Records per page, up to 1000.

integer

default:"0"

Records to skip. Combine with limit to paginate.

Example

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

Response

{
  "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

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.

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.

Pagination

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

{ "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.

Next steps

Runs and results — the full lifecycle
titan_crawl — the tool that most often needs polling

Get started

Tool reference

How it works

Integration examples

Parameters

Example

Response

Response fields

Polling

Warnings you may see

Ownership

Using the run elsewhere

Next steps

​Parameters

​Example

​Response

​Response fields

​Polling

​Pagination

​Warnings you may see

​Ownership

​Using the run elsewhere

​Next steps

Parameters

Example

Response

Response fields

Polling

Pagination

Warnings you may see

Ownership

Using the run elsewhere

Next steps