Reference
API reference
The base URL is https://api.siftzo.com. Every endpoint needs an API key, and every response has an X-Request-Id header.
Authentication
Send your key in one of these headers:
X-API-Key: sz_live_...
Authorization: Bearer sz_live_...A missing, unknown or revoked key gets 401 invalid_api_key. Revoking a key takes effect within 60 seconds.
POST /v1/scrape
Fetch a page. The body is a JSON object; unknown fields are rejected with 400 invalid_request, so typos do not pass silently.
urlstringrequired- The page to fetch. Absolute
httporhttpsURL, at most 2,048 characters, on a public host. Private and internal addresses are refused, and so are ports below 1024 other than 80 and 443. renderauto | never | alwaysdefaultautoneveruses only HTTP,alwaysuses only the browser,autostarts where the domain usually succeeds and escalates to the browser when blocked. See Rendering.countrystring- Exit country as an ISO 3166-1 alpha-2 code, for example
deorus. Case does not matter. See Proxies. sessionstring- 1–64 characters of
A-Z a-z 0-9 _. Requests with the same session keep the same exit IP for 10 minutes. Sessions are private to your account. methodGET | HEAD | POSTdefaultGET- HTTP method sent to the target.
headersobject- Extra request headers as
{ name: value }, at most 30. They are merged into the browser-like default headers, not replacing them. Connection and proxy headers such asHost,Content-Length,ConnectionandProxy-*are refused. bodystring- Request body for the target. Only with
method: "POST", at most 1 MB. actionsarray- Up to 20 steps the browser performs on the loaded page before it is captured: click, type, press, scroll, wait and wait_for. Needs the browser, like
wait_for. See actions. wait_forstring- CSS selector (at most 256 characters) to wait for before the page is captured, within the timeout. Needs the browser: a request with
wait_foralways runs on the browser tier, and is refused withrender: "never". If the element never appears, the request fails with408 timeoutand is not billed. screenshotbooleandefaultfalse- Return a PNG of the viewport, base64-encoded, in
screenshot. Runs on the browser tier, and is refused withrender: "never". screenshot_full_pagebooleandefaultfalse- With
screenshot: capture the whole page, up to 10,000 pixels tall, instead of the viewport (see Screenshots). iframesbooleandefaultfalse- Include the content of the page's iframes, also from other domains and nested ones, in the HTML (and the Markdown). Each frame's body follows its iframe in a
<div data-siftzo-iframe="frame URL">, with absolute links and without scripts. At most 50 frames, 5 levels deep. Runs on the browser tier, and is refused withrender: "never". timeout_msintegerdefault60000- Deadline for the whole request including retries, between 5000 and 90000.
asyncbooleandefaultfalse- Queue the request and return
202with a job ID. See GET /v1/jobs/{id}. formatjson | raw | markdown | raw_markdowndefaultjsonrawreturns the target body as-is, with metadata inX-Siftzo-*headers.markdownreturns the JSON result with the page converted to Markdown intarget.markdown, andraw_markdownreturns only the Markdown. See Markdown.rawandraw_markdownare not available for async requests.include_htmlbooleandefaultfalse- Only with
format: "markdown": also return the originaltarget.bodyandtarget.body_encoding. Refused with any other format. webhook_urlstring- Only with
async: true: Siftzo sends a signedjob.finishedevent to thishttpsURL when the job has finished. See Webhooks.
curl https://api.siftzo.com/v1/scrape \
-H "X-API-Key: $SIFTZO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://example.com/search",
"method": "POST",
"headers": {"Accept-Language": "de-DE"},
"body": "q=shoes",
"country": "de",
"render": "never",
"timeout_ms": 30000
}'Response
With format: "json" (the default) a finished request returns 200 and this object:
{
"id": "01K6ZQ3M8V4T2NXB7RJ5HCWDGE",
"status": "done",
"target": {
"url": "https://example.com/",
"status_code": 200,
"headers": {
"content-type": ["text/html; charset=UTF-8"]
},
"body": "<!doctype html><html>…",
"body_encoding": "utf8"
},
"screenshot": null,
"tier": "http",
"attempts": 1,
"credits": 1,
"duration_ms": 812
}idstring- Request ID. The same value as the X-Request-Id header and the job ID.
statusdone | failed- Whether Siftzo got a usable answer from the target.
target.urlstring- Final URL after redirects. Omitted when unknown.
target.status_codeinteger- HTTP status the target answered with. 4xx and 5xx answers are valid results.
target.headersobject- Response headers. Each value is an array of strings, because a header can repeat.
target.bodystring- The response body, at most 10 MB. With
format: "markdown"only wheninclude_htmlis set or there is no Markdown. target.markdownstring | null- Only with
format: "markdown": the page as Markdown, ornullwhen the response could not be converted. target.body_encodingutf8 | base64- utf8 for text, base64 when the body is not valid UTF-8.
screenshotstring | null- Base64 PNG when screenshot was requested, otherwise null.
tierhttp | browser- The tier that produced the result.
attemptsinteger- Attempts made, at most 3.
creditsinteger- Credits charged for this request. 0 when it failed.
duration_msinteger- Time spent inside Siftzo, in milliseconds.
errorobject- Only when
statusisfailed:codeandmessage. See Errors.
If every attempt failed, the API answers with the matching error status (for example 424 for target_blocked) and the same object with status: "failed", no target, and an error:
{
"id": "01K6ZQ7F2B9X4M1NQ8T3RJ6VWC",
"status": "failed",
"screenshot": null,
"tier": "browser",
"attempts": 3,
"credits": 0,
"duration_ms": 41230,
"error": {
"code": "target_blocked",
"message": "the target blocked every attempt"
}
}Raw format
With format: "raw" a successful request returns 200 with the target body as the response body and the target's Content-Type. The rest is in headers:
| Header | Value |
|---|---|
X-Siftzo-Status-Code | Status the target answered with |
X-Siftzo-Tier | http or browser |
X-Siftzo-Attempts | Attempts made |
X-Siftzo-Credits | Credits charged |
X-Siftzo-Final-Url | Final URL after redirects, when known |
Errors are still returned as JSON, so check the HTTP status before you use the body.
Markdown
With format: "markdown" Siftzo converts the final HTML to Markdown and returns it in target.markdown. It keeps the main content: the <main> or <article> element when the page has one, without navigation, header, footer, sidebars, scripts, styles, forms, iframes and SVG. Headings, lists, tables (as GitHub-flavoured Markdown), code blocks, images and links stay; links are made absolute against the final URL. It costs the same credits as json.
{
"id": "01K6ZQ3M8V4T2NXB7RJ5HCWDGE",
"status": "done",
"target": {
"url": "https://example.com/",
"status_code": 200,
"headers": {
"content-type": ["text/html; charset=UTF-8"]
},
"markdown": "# Example Domain\n\nThis domain is for use in illustrative examples…"
},
"screenshot": null,
"tier": "http",
"attempts": 1,
"credits": 1,
"duration_ms": 812
}target.bodyandtarget.body_encodingare left out unless you setinclude_html: true.- Text responses (plain text, Markdown, JSON, XML) are returned as they are in
markdown. - Binary responses, such as images or PDFs, have
markdown: nulland the originalbodyandbody_encoding.
format: "raw_markdown" returns the Markdown itself as the response body, with Content-Type: text/markdown; charset=utf-8 and the same X-Siftzo-* headers as raw. If the response could not be converted, you get the original body with its own content type and X-Siftzo-Format: raw. Like raw, it is only available for sync requests.
curl -G https://api.siftzo.com/v1/scrape \
-H "X-API-Key: $SIFTZO_API_KEY" \
--data-urlencode "url=https://example.com/" \
-d format=raw_markdownGET /v1/scrape
The same as a sync POST, with parameters in the query string. Handy for curl and browsers. Supported: url, render, country, session, wait_for, screenshot, screenshot_full_page, iframes (true/false), timeout_ms, format and include_html. Custom method, headers, body, async and webhook_url are only available with POST.
curl -G https://api.siftzo.com/v1/scrape \
-H "X-API-Key: $SIFTZO_API_KEY" \
--data-urlencode "url=https://example.com/?page=2" \
-d render=never -d format=rawGET /v1/jobs/{id}
Status and result of an async request. Send async: true to POST /v1/scrape to create one; the answer is 202 Accepted with a Location header and:
{
"id": "01K6ZQ3M8V4T2NXB7RJ5HCWDGE",
"status": "queued",
"status_url": "/v1/jobs/01K6ZQ3M8V4T2NXB7RJ5HCWDGE"
}status moves from queued to running to done or failed. Until it has finished, the job endpoint returns only id and status. After that it returns the full result object described above, always with HTTP 200; a failed job has status: "failed" and an error.
A finished job is rendered in the format it was submitted with, so a job sent with format: "markdown" returns target.markdown.
Results are kept for 24 hours. After that, or for a job that belongs to another account, the answer is 404 not_found.
Instead of polling, pass a webhook_url with the request and Siftzo calls it when the job has finished; see Webhooks. To submit up to 1,000 requests at once, use Batch.
GET /v1/usage
Credits and concurrency for the current month (UTC). Credits and concurrency belong to your organization; a key that belongs to a team also gets that team's share and monthly cap.
{
"period": "2026-10",
"credits_used": 1240,
"credits_limit": 25000,
"credits_remaining": 23760,
"concurrency_limit": 10,
"concurrency_in_use": 2,
"team": {
"id": "grp_01k6…",
"credits_used": 310,
"credits_limit": 5000,
"credits_remaining": 4690
}
}periodstring- The month, as YYYY-MM in UTC.
credits_usedinteger- Credits used this month, including credits set aside for requests still running.
credits_limitinteger | null- Your monthly limit: included credits plus any overage you allow. null means no limit.
credits_remaininginteger | null- credits_limit minus credits_used, never below 0.
concurrency_limitinteger- Requests you can have running at once.
concurrency_in_useinteger- Requests running right now, sync and async.
teamobject- Only for a key that belongs to a team: the team's id, its credits_used this month, and credits_limit and credits_remaining for its monthly cap (null when the team has no cap of its own).
Unknown paths return 404 not_found. All errors use the shape described in Errors.