run_id you get back is literally the Titan execution_id.
That equivalence matters: anything you can do with an execution in the API, dashboard, analytics, or billing, you can do with a run_id from an agent.
Synchronous or asynchronous
Tools try to return results inside the call. When work outlives the wait window, they hand back arun_id instead of failing.
Override with
wait_for_completion. Setting it to false returns a run_id immediately; setting it to true on a crawl only makes sense for small, shallow runs.
The wait window
timeout_seconds controls how long a tool waits, capped at 30 seconds.
Exceeding it is not an error. The run keeps going on Titan’s side and you get:
next_step warning is the signal to poll. Re-issuing the original tool call instead would start a second billable run for work already in progress.
Statuses
partial is common and usually fine. A fetch of 50 URLs where 47 succeed is a partial run with 47 usable pages.
Reading results
Results arrive one of two ways: In the tool response when the run finished inside the wait window.titan_search returns results[], titan_fetch returns pages[] and failed[], titan_crawl returns discovered_urls[] or pages[].
Through titan_get_run when it did not. Records are aggregated across all steps of the run, paginated with limit and offset.
usage.records_returned with usage.records_available to know whether more pages remain.
The usage object
Every run reports what it cost:
While a run is in flight,
billing_status is pending and only credits_estimated is meaningful. Both settle once the run reaches a terminal status. See Credits and usage.
A run is a Titan execution
The samerun_id works across the platform:
mcp_capability and target_platform.
Handling runs well
Next steps
- titan_get_run — polling and pagination in detail
- Credits and usage — what a run costs
- Idempotency and retries — retrying without paying twice