POST /scrape

Scrape a single URL and return structured JSON. Billing is prepaid: the cost depends on the engine and proxy_type you pick (see Pricing). You are debited only on a real success (success: true and blocked: false) — failed or blocked requests are not billed.

POST https://api.tallyscrape.com/scrape

Request

Headers

string

required

Your API key (starts with spy_). See Authentication.

string

required

Must be application/json.

Body

string

required

The target URL to scrape. Must be a valid http or https URL.

string

default:"static"

Rendering engine. static uses a fast HTTP fetch. js runs the page in a real headless browser (for client-side rendered content) and costs more credits.Allowed values: static, js.

object

Optional map of name → CSS selector for targeted extraction. Each result is returned under extracted[name]. Example: { "price": ".price", "title": "h1" }.

boolean

default:true

Respect the target’s robots.txt. Defaults to true (the safe choice). Set to false to ignore it.

number

default:20

Request timeout in seconds. Must be greater than 0 and at most 120.

string

default:"none"

Proxy tier. none connects directly. datacenter and residential route through the server-owned proxy pools (you never provide proxy credentials). Residential may require unlocking — see Errors (403).Allowed values: none, datacenter, residential.

Response

string

The requested URL.

string

The URL after any redirects.

integer

HTTP status returned by the target.

boolean

Whether the fetch succeeded. Only a true success (with blocked: false) is billed.

string

The engine used (static or js).

integer

Request time in milliseconds (the billing basis).

string | null

Error message when success is false, otherwise null.

boolean

true when an anti-bot page is detected. Blocked requests are not billed.

boolean

Whether a proxy was actually used for the returned request. May differ from the requested proxy_type: if the pool is unavailable, it falls back to a direct connection (billed at the none rate).

string | null

The page title.

object

Meta tags (e.g. description), as name → content.

object

Headings grouped by level, e.g. { "h1": [...], "h2": [...] }.

array

Links as { "text": ..., "href": ... }, with absolute URLs.

array

Absolute image URLs.

string | null

Visible page text (scripts and styles excluded).

object

Results of your selectors, keyed by the names you provided.

Examples

curl -X POST https://api.tallyscrape.com/scrape \
  -H "X-API-Key: spy_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://quotes.toscrape.com/js/",
    "engine": "js",
    "proxy_type": "datacenter",
    "selectors": { "quotes": ".quote .text" }
  }'

import requests

resp = requests.post(
    "https://api.tallyscrape.com/scrape",
    headers={"X-API-Key": "spy_your_api_key"},
    json={
        "url": "https://quotes.toscrape.com/js/",
        "engine": "js",
        "proxy_type": "datacenter",
        "selectors": {"quotes": ".quote .text"},
    },
)
data = resp.json()
print(data["extracted"]["quotes"])

const resp = await fetch("https://api.tallyscrape.com/scrape", {
  method: "POST",
  headers: {
    "X-API-Key": "spy_your_api_key",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://quotes.toscrape.com/js/",
    engine: "js",
    proxy_type: "datacenter",
    selectors: { quotes: ".quote .text" },
  }),
});
const data = await resp.json();
console.log(data.extracted.quotes);

import java.net.URI;
import java.net.http.*;

var body = """
    {"url":"https://quotes.toscrape.com/js/","engine":"js","proxy_type":"datacenter","selectors":{"quotes":".quote .text"}}
    """;

var request = HttpRequest.newBuilder()
    .uri(URI.create("https://api.tallyscrape.com/scrape"))
    .header("X-API-Key", "spy_your_api_key")
    .header("Content-Type", "application/json")
    .POST(HttpRequest.BodyPublishers.ofString(body))
    .build();

var response = HttpClient.newHttpClient()
    .send(request, HttpResponse.BodyHandlers.ofString());
System.out.println(response.body());

Example response

{
  "url": "https://quotes.toscrape.com/js/",
  "final_url": "https://quotes.toscrape.com/js/",
  "status_code": 200,
  "success": true,
  "engine": "js",
  "elapsed_ms": 8734,
  "error": null,
  "blocked": false,
  "proxy_used": true,
  "title": "Quotes to Scrape",
  "meta": {},
  "headings": { "h1": ["Quotes to Scrape"] },
  "links": [{ "text": "Login", "href": "https://quotes.toscrape.com/login" }],
  "images": [],
  "text": "Quotes to Scrape ...",
  "extracted": {
    "quotes": ["“The world as we have created it is a process of our thinking...”"]
  }
}

Get started

API reference

Going further

Request

Headers

Body

Response

Examples

Example response

​Request

​Headers

​Body

​Response

​Examples

​Example response

Request

Headers

Body

Response

Examples

Example response