Cloudflare Interstitial (Challenge Page) Solver API: cf_clearance Cookie

Pass the Cloudflare interstitial challenge page with the SolveHub API and reuse the clearance cookie with the returned user agent and the same proxy. Request fields, cURL example and errors.

For authorized QA automation and browser integration. Use only on websites and workflows you have permission to test.

For Cloudflare challenge (interstitial) pages, where you usually need to reuse the cf_clearance cookie afterwards. websiteURL and the three HTTP proxy fields proxyType,proxyAddress,proxyPort are required. The optional siteKey is the page's Turnstile sitekey, which lets the platform take a shortcut path; when omitted (the default), the full page is solved. source:true requests the post-challenge HTML in the result (if it was fetched successfully); method supports only GET or POST and defaults to GET. useragent is optional.

Browser selection

Optional useragent selects browser family, platform and major version for Chrome/Chromium or Firefox. An unavailable version causes a task failure. Omit it to use the default browser. Replay cookies with the same proxy and the actual solution.useragent, rather than assuming the requested string is the returned identity.

Request fields

The outer type and task are required; all task.* paths below are inside the task object. Field names are case-sensitive. Length limits are measured in UTF-8 bytes.

Field	Type	Required	Limit	Description
`type`	String	Yes	Must be `interstitial`	Platform task type.
`task`	JSON object	Yes	≤ 7 MiB	Task parameters for this type.
`task.type`	String	No	Must be `interstitial` if provided	Compatibility with the legacy request format; can be omitted in new integrations.
`task.websiteURL`	HTTP(S) URL	Yes	≤ 2048 bytes	Full URL of the target page to solve, without username or password.
`task.siteKey`	String	No	≤ 256 bytes	The page's Turnstile sitekey; when provided, a shortcut path may be used; when omitted, the full page is processed.
`task.useragent`	String	No	≤ 512 bytes	Custom browser User-Agent; for subsequent requests, prefer the actually returned `solution.useragent`.
`task.source`	Boolean	No	`true` / `false`	Asks for the post-challenge HTML to be included in the result; whether it is returned depends on the actual result.
`task.method`	String	No	`GET` / `POST`	Page navigation method; `GET` is used when omitted.
`task.proxyType`	String	Yes	`http` only	Proxy protocol; must be `http` if provided.
`task.proxyAddress`	String	Yes	≤ 256 bytes	Proxy IP or hostname; must be provided together with `proxyPort`.
`task.proxyPort`	String	Yes	1–5 bytes, value 1–65535	Proxy port; must be a quoted numeric string.
`task.proxyLogin`	String	No	≤ 256 bytes	Username if the proxy requires authentication; must not be provided without the address and port.
`task.proxyPassword`	String	No	≤ 256 bytes	Password if the proxy requires authentication; must not be provided without the address and port.

Create request example

{
  "type": "interstitial",
  "task": {
    "websiteURL": "https://example.com/protected",
    "siteKey": "0x4AAAAAAA_EXAMPLE",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080",
    "source": true
  }
}

cURL call

Replace the Key, site information, and proxy in the example with your actual values; keep the Idempotency-Key unchanged for the same business request.

curl -sS -X POST 'https://www.tiam.codes/v1/tasks' \
  -H 'Authorization: Bearer sh_REPLACE_ME' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: example-interstitial-0001' \
  --data-binary @- <<'JSON'
{
  "type": "interstitial",
  "task": {
    "websiteURL": "https://example.com/protected",
    "siteKey": "0x4AAAAAAA_EXAMPLE",
    "proxyType": "http",
    "proxyAddress": "203.0.113.10",
    "proxyPort": "8080",
    "source": true
  }
}
JSON

Create response and polling

A successful creation returns HTTP 202, and the initial status is usually queued. Save the taskId and call GET /v1/tasks/{taskId} roughly every 2–3 seconds. The soft processing time limit for this type is 180 seconds; after the soft limit the task may enter uncertain. Results of accepted tasks can still be verified; clients should not blindly recreate the task with a new Idempotency-Key.

Result fields

Read solution only when status=completed; the table below lists common fields, and the actual fields are those in the task's response.

Field	Type	How to read
`solution.cookies`	Object	Cookies produced by the solving session; may include `cf_clearance`.
`solution.useragent`	String	User-Agent to reuse together with the cookies and the same egress.
`solution.html`	String, optional	Present only when `source:true` was requested and the page was fetched successfully.

After completed, read solution.cookies, which may contain cf_clearance; also read solution.useragent, and continue browsing with the same proxy IP, User-Agent, and full cookie set. solution.html is present only when source:true was set and the page content was fetched successfully. Sample result: {"cookies":{"cf_clearance":"EXAMPLE_CLEARANCE"},"useragent":"Mozilla/5.0 ..."}.

Failures and troubleshooting

All three HTTP proxy fields are required; if the returned cookies cannot be reused, check the proxy egress, the User-Agent, the full cookie set, and whether the target page has expired.

Common errors on create requests are 400 INVALID_TASK, 402 INSUFFICIENT_BALANCE, 429 TASK_LIMIT_EXCEEDED, and 503 TYPE_UNAVAILABLE. When a created task fails, the public error code is TASK_FAILED or TASK_TIMEOUT; uncertain corresponds to TASK_UNCERTAIN. See the Platform API reference for details.

The processing window starts after task creation is confirmed; queue waiting does not consume it. The current node timeout is approximately 120 seconds; the platform allows a 180-second soft window for transport and result polling.

Supported User Agents