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:

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 http or https URL, 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 | alwaysdefault auto
never uses only HTTP, always uses only the browser, auto starts 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 de or us. 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 | POSTdefault GET
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 as Host, Content-Length, Connection and Proxy-* 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_for always runs on the browser tier, and is refused with render: "never". If the element never appears, the request fails with 408 timeout and is not billed.
screenshotbooleandefault false
Return a PNG of the viewport, base64-encoded, in screenshot. Runs on the browser tier, and is refused with render: "never".
screenshot_full_pagebooleandefault false
With screenshot: capture the whole page, up to 10,000 pixels tall, instead of the viewport (see Screenshots).
iframesbooleandefault false
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 with render: "never".
timeout_msintegerdefault 60000
Deadline for the whole request including retries, between 5000 and 90000.
asyncbooleandefault false
Queue the request and return 202 with a job ID. See GET /v1/jobs/{id}.
formatjson | raw | markdown | raw_markdowndefault json
raw returns the target body as-is, with metadata in X-Siftzo-* headers. markdown returns the JSON result with the page converted to Markdown in target.markdown, and raw_markdown returns only the Markdown. See Markdown. raw and raw_markdown are not available for async requests.
include_htmlbooleandefault false
Only with format: "markdown": also return the original target.body and target.body_encoding. Refused with any other format.
webhook_urlstring
Only with async: true: Siftzo sends a signed job.finished event to this https URL when the job has finished. See Webhooks.
Example
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:

200 OK
{
  "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 when include_html is set or there is no Markdown.
target.markdownstring | null
Only with format: "markdown": the page as Markdown, or null when 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 status is failed: code and message. 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:

424 Failed Dependency
{
  "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:

Raw format headers
HeaderValue
X-Siftzo-Status-CodeStatus the target answered with
X-Siftzo-Tierhttp or browser
X-Siftzo-AttemptsAttempts made
X-Siftzo-CreditsCredits charged
X-Siftzo-Final-UrlFinal 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.

200 OK
{
  "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.body and target.body_encoding are left out unless you set include_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: null and the original body and body_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.

Example
curl -G https://api.siftzo.com/v1/scrape \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  --data-urlencode "url=https://example.com/" \
  -d format=raw_markdown

GET /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.

Example
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=raw

GET /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:

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

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