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
- Create a free account. The Free plan includes 1,000 credits a month and needs no card.
- Open the dashboard, go to API keys and create a key. It is shown once, so copy it right away.
- Store it in an environment variable rather than in your code:
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"}'const res = await fetch("https://api.siftzo.com/v1/scrape", {
method: "POST",
headers: {
"X-API-Key": process.env.SIFTZO_API_KEY,
"Content-Type": "application/json",
},
body: JSON.stringify({ url: "https://example.com", country: "de" }),
signal: AbortSignal.timeout(90_000),
});
const result = await res.json();
if (!res.ok) throw new Error(result.error.code);
console.log(result.target.status_code, result.tier, result.credits);
console.log(result.target.body.slice(0, 200));import os
import requests
res = requests.post(
"https://api.siftzo.com/v1/scrape",
headers={"X-API-Key": os.environ["SIFTZO_API_KEY"]},
json={"url": "https://example.com", "country": "de"},
timeout=90,
)
result = res.json()
res.raise_for_status()
print(result["target"]["status_code"], result["tier"], result["credits"])
print(result["target"]["body"][:200])package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
"os"
"time"
)
func main() {
payload, _ := json.Marshal(map[string]any{"url": "https://example.com", "country": "de"})
req, _ := http.NewRequest("POST", "https://api.siftzo.com/v1/scrape", bytes.NewReader(payload))
req.Header.Set("X-API-Key", os.Getenv("SIFTZO_API_KEY"))
req.Header.Set("Content-Type", "application/json")
client := &http.Client{Timeout: 90 * time.Second}
res, err := client.Do(req)
if err != nil {
panic(err)
}
defer res.Body.Close()
var result struct {
Tier string `json:"tier"`
Credits int `json:"credits"`
Target struct {
StatusCode int `json:"status_code"`
Body string `json:"body"`
} `json:"target"`
}
json.NewDecoder(res.Body).Decode(&result)
fmt.Println(res.StatusCode, result.Target.StatusCode, result.Tier, result.Credits)
}<?php
$ch = curl_init("https://api.siftzo.com/v1/scrape");
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 90,
CURLOPT_HTTPHEADER => [
"X-API-Key: " . getenv("SIFTZO_API_KEY"),
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => json_encode(["url" => "https://example.com", "country" => "de"]),
]);
$result = json_decode(curl_exec($ch), true);
echo $result["target"]["status_code"], " ", $result["tier"], " ", $result["credits"], PHP_EOL;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
{
"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_codeis 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.bodyis the page. If it is not valid UTF-8 (an image, a PDF) it is base64 andbody_encodingsaysbase64.tier,attemptsandcreditstell 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:
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:
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}'{
"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.
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
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.