POST /analyse

/analyse answers a broad / interpretive question about a page. It fetches HTML, compresses it to article markdown, and runs one LLM pass. It does not emit a CSS plan.

Not scrape

Do not send actions or engine. Analyse is not a CSS planner. Use POST /scrape when you need exact, re-runnable fields (title, price, link lists).

3 credits per URL. Cap: 10 URLs per request.

Request

POST /analyse
Authorization: Bearer <token>
Content-Type:  application/json

{
  url: string | string[];   // one http(s) URL, or an array (max 10)
  query: string;            // 1–2000 chars — plain-English question about the page

  headers?: Record<string, string>; // same validation and redirect scope as scrape
  sessionId?: string;       // replay matching cookies from an owned session profile

  options?: {
    timeoutMs?: number;     // fetch abort; default 30000, max 120000
  };

  // Proxy (all optional). Same as /scrape — see /docs/engines#proxies.
  useProxy?:      boolean | string;  // true = built-in pool; "us" geo-targets it
  myProxyUrl?:    string;            // BYO: "http://user:pass@host:port"
  myProxyConfig?: {
    server:    string;
    username?: string;
    password?: string;
  };
}

query is required. Do not send actions, engine, or fetch. Analyse uses the same plain-HTTP transport as HTML/JSON scrape: custom headers and session cookies stay on the initial origin, redirects are checked, and non-2xx previews are bounded to 2048 characters. Browser options and localStorage replay are unavailable.

New analyse results share scrape’s envelope and omit the former engine result field. Stored historical results are preserved and may still contain it.

Multiple URLs

url may be an array (max 10). Each distinct URL is its own queued job (3 credits each), in first-occurrence order. A failed URL returns data: null + error; siblings still return. batchId is set only when more than one distinct URL is admitted.

Response

HTTP 200 returns an array — one item per deduplicated URL. ?wait=false or the wait deadline returns HTTP 202 with full jobs, including completed siblings. Poll those same jobs; disconnecting does not cancel them. Submission headers include X-Scrape-Job-Ids and, for batches, X-Scrape-Batch-Id.

Each completed result has this shape:

{
  url: string;
  status?: number;
  response?: {
    requestedUrl: string;
    finalUrl: string;
    status: number;
    statusText: string;
    contentType: string | null;
    bodyPreview?: string;
    bodyTruncated?: boolean;
  };
  data: {
    result: Record<string, unknown>;  // free-form JSON shaped to your query
    evidence: Array<{ text: string; why?: string }>;
    confidence: 'high' | 'medium' | 'low';
  } | null;
  tookMs: number;
  antibot: Array<{ provider: string; detection: string; blocked: boolean; version?: string; sitekey?: string }>;
  error?: { message: string; /* … */ };
  jobId: string;
  batchId?: string;
}

antibot is an array of detected measures (AntibotMeasure[]), or [] when none are detected. Each measure identifies its provider, detection and whether it blocked the request; version and sitekey are optional.

On failure data is null and error is set. Inspect the row later via the Jobs API.

Errors

Status	Code	Cause
400	VALIDATION_ERROR / MALFORMED_REQUEST	Invalid fields or malformed body.
400	BLOCKED_URL	Admission rejected a URL.
401	UNAUTHENTICATED	Bearer credential did not resolve.
402	QUOTA_EXCEEDED	Credit admission failed; credit values are under error.details.
503	CAPACITY_EXCEEDED	Pending queue is full; Retry-After: 5.

Failures use { error: { code, message, details? } }; see Errors and response contracts. Accepted operation failures remain on individual jobs/results: HTTP 200 can contain failed URLs with data: null and error, while siblings still return.

Example

curl -sS -X POST https://api.scrapesilo.com/analyse \
  -H "Authorization: Bearer sf_…" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://scrapesilo.com/fixtures/prose",
        "query": "Outline the article sections and state the main claim in one sentence."
      }'

[
  {
    "url": "https://scrapesilo.com/fixtures/prose",
    "data": {
      "result": {
        "sections": [
          "Field extraction is not interpretation",
          "What a scrape is for",
          "What analyse is for",
          "Why the split is documented twice",
          "A note on emptiness"
        ],
        "mainClaim": "A scrape should return the same fields on every run; interpretation belongs on a separate analyse call."
      },
      "evidence": [{ "text": "The main claim of this article is that a scrape should return the same fields on every run", "why": "lead paragraph" }],
      "confidence": "high"
    },
    "tookMs": 1840,
    "antibot": [],
    "jobId": "job_…"
  }
]

/analyse is also the analyse MCP tool.

Copy for an agent

Use POST /analyse for interpretation (outline, summary, “is X present?”, roles). Do not send actions or engine. Required: url + query (1–2000 chars). Optional: headers, sessionId, proxies, options.timeoutMs. Max 10 URLs, 3 credits each. Completed HTTP 200 returns an array; HTTP 202 returns jobs to poll. In a completed array, each item has data: { result, evidence, confidence } or data: null + error. For exact CSS fields use POST /scrape with engine + actions.

curl -sS -X POST https://api.scrapesilo.com/analyse \
  -H "Authorization: Bearer sf_…" \
  -H "Content-Type: application/json" \
  -d '{
        "url": "https://scrapesilo.com/fixtures/prose",
        "query": "Outline the article sections and state the main claim in one sentence."
      }'