Getting started

Quickstart

Create a key, send a request and read the result. Then render a page in a browser and run a request as an async job.

1. Get an API key

  1. Create a free account. The Free plan includes 1,000 credits a month and needs no card.
  2. Open the dashboard, go to API keys and create a key. It is shown once, so copy it right away.
  3. Store it in an environment variable rather than in your code:
Terminal
export SIFTZO_API_KEY="sz_live_..."

Treat the key like a password. Anyone with it can spend your credits. If it leaks, revoke it in the dashboard; a revoked key stops working within 60 seconds.

2. Send your first request

POST the URL you want to /v1/scrape. The call waits until the page is fetched and returns it as JSON.

curl https://api.siftzo.com/v1/scrape \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "country": "de"}'

For quick tests you can also use GET with query parameters: /v1/scrape?url=https://example.com. URL-encode the target if it has its own query string.

3. Read the response

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
}
  • target.status_code is what the website answered. A 404 from the target is still a result, so check this field, not only the HTTP status of the API call.
  • target.body is the page. If it is not valid UTF-8 (an image, a PDF) it is base64 and body_encoding says base64.
  • tier, attempts and credits tell you how the page was fetched and what it cost.

4. Render a page in a browser

By default (render: "auto") Siftzo starts with a fast HTTP request and switches to a browser if the site blocks it. For pages that build their content with JavaScript, ask for the browser and wait for the element you need:

Terminal
curl https://api.siftzo.com/v1/scrape \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://quotes.toscrape.com/js/",
    "render": "always",
    "wait_for": ".quote",
    "screenshot": true
  }'

A browser request costs 10 credits. screenshot is a base64 PNG of the viewport. Read more in Rendering & tiers.

5. Run it as an async job

For long-running pages or large batches, add "async": true. The API answers at once with 202 Accepted and a job ID:

Terminal
curl https://api.siftzo.com/v1/scrape \
  -H "X-API-Key: $SIFTZO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com", "async": true}'
202 Accepted
{
  "id": "01K6ZQ3M8V4T2NXB7RJ5HCWDGE",
  "status": "queued",
  "status_url": "/v1/jobs/01K6ZQ3M8V4T2NXB7RJ5HCWDGE"
}

Poll the job until status is done or failed. While it is queued or running you get only the ID and status; when it has finished you get the same result object as a sync request. Results are kept for 24 hours.

Terminal
curl https://api.siftzo.com/v1/jobs/01K6ZQ3M8V4T2NXB7RJ5HCWDGE \
  -H "X-API-Key: $SIFTZO_API_KEY"

A queued or running job holds one of your concurrent request slots until it finishes, the same as a sync request.

6. Check your usage

Terminal
curl https://api.siftzo.com/v1/usage -H "X-API-Key: $SIFTZO_API_KEY"

See the API reference for the fields, and Errors for what to do when something goes wrong.