Fetch

Load a page and get its content back. Tilion handles rendering, anti-bot recovery, and optional replay capture, so you do not have to drive the browser yourself.

POST /v1/fetch

Request

{ "session_id": "sess_1f68f2e37b7d4e339112b906a66200d4", "url": "https://example.com" }

Field	Type	Default	Notes
`session_id`	string	required	An existing session
`url`	string	required	Public `http`/`https` only
`render`	boolean	`true`	Execute JavaScript. `false` is faster for static pages
`include_html`	boolean	`false`	Also return the rendered DOM
`record`	boolean	`false`	Capture a session replay
`async_mode`	boolean	`false`	Return a `job_id` immediately

Response

{
  "session_id": "sess_1f68...",
  "final_url": "https://example.com/",
  "status": "ok",
  "content_ok": true,
  "title": "Example Domain",
  "text": "Example Domain\nThis domain is for use in illustrative examples...",
  "html_len": 1256,
  "html": null,
  "captcha": "none",
  "self_healed": false,
  "recovery": null,
  "replay_url": null,
  "detected": null,
  "status_reconciled": null,
  "job_id": null
}

Field	Type	Notes
`status`	string	`ok`, `blocked`, `error`, `pending`
`content_ok`	boolean	Authoritative. `true` means a real document came back
`final_url`	string	After redirects
`title`	string \| null
`text`	string	Extracted text content
`html`	string \| null	Only when `include_html: true`
`html_len`	integer	Rendered DOM size in bytes
`captcha`	string	`none`, or the challenge family detected
`self_healed`	boolean	A block was detected and recovered automatically
`recovery`	object \| null	Attempts, winning strategy, cost
`replay_url`	string \| null	Only when `record: true`
`detected`	object \| null	Challenge classification
`status_reconciled`	string \| null	Set when `blocked` was flipped to `ok` on content
`job_id`	string \| null	Set when `async_mode: true`

Trust `content_ok` over `status`

Some sites answer with a non-200 while still serving a complete document, and some serve a soft-block page with a 200. content_ok is the signal that reconciles both.

if (!res.content_ok) {
  // genuinely no usable content
}

When Tilion determines a blocked result actually carried real content, it flips the status and records the original in status_reconciled.

Examples

curl -X POST https://api.tilion.dev/v1/fetch \
  -H "Authorization: Bearer $TILION_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"session_id":"'"$SESSION_ID"'","url":"https://example.com"}'

const r = await fetch('https://api.tilion.dev/v1/fetch', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TILION_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ session_id: sessionId, url: 'https://example.com' }),
});
const page = await r.json();
if (page.content_ok) console.log(page.title, page.text.slice(0, 200));

page = requests.post(
    "https://api.tilion.dev/v1/fetch",
    headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
    json={"session_id": session_id, "url": "https://example.com"},
).json()
if page["content_ok"]:
    print(page["title"])

Use async mode for slow pages

A synchronous fetch that outruns its deadline returns 504. For slow sites, set async_mode: true to get a job_id back immediately, then poll it as described in Async jobs.

Recording a replay

Set record: true and the response carries replay_url. Replays covers how to play one back.

Errors

Status	Meaning
`400`	Malformed body, or a URL that is not public `http`/`https`
`402`	Out of credits, or monthly quota exhausted
`404`	`session_id` does not exist or is not yours
`409`	Session exists but has no live browser
`429`	Rate limit
`504`	Deadline exceeded; retry with `async_mode`

Extract runs the same fetch and returns the result as clean markdown for a model context. Search returns search-engine results without building the query flow yourself. Both need a session, which is covered in Sessions.

Get started

MCP

Sessions

Fetch & jobs

Content

Agent & tasks

Live view & recordings

Account

Reference

Request

Response

Trust `content_ok` over `status`

Examples

Use async mode for slow pages

Recording a replay

Errors

​Request

​Response

​Trust content_ok over status

​Examples

​Use async mode for slow pages

​Recording a replay

​Errors

​Related

Request

Response

Trust `content_ok` over `status`

Examples

Use async mode for slow pages

Recording a replay

Errors

Related