POST /analyse

import { Aside } from ‘@astrojs/starlight/components’;

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

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

  fetch?: 'html';           // plain HTTP fetch (default). Only accepted value.

  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.

Multiple URLs

url may be an array (max 10). Each URL is its own execution (3 credits each). A failed URL returns data: null + error; siblings still return. batchId is set only when more than one URL is sent.

Response

Always an array — one item per (deduped) URL:

{
  url: string;
  status?: number;
  data: {
    result: Record<string, unknown>;  // free-form JSON shaped to your query
    evidence: Array<{ text: string; why?: string }>;
    confidence: 'high' | 'medium' | 'low';
  } | null;
  engine: 'analyse';
  tookMs: number;
  antibot: { detected: boolean; /* … */ };
  error?: { message: string; /* … */ };
  executionId: string;
  batchId?: string;
}

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

Errors

Status	Body	Cause
`400`	`{ "error": "invalid analyse request", "issues": [...] }`	Body failed validation (`query` missing, more than 10 URLs, `fetch` not `"html"`, …).
`401`	`{ "error": "invalid api key" }`	Bearer didn’t resolve.
`402`	`{ "error": "credit quota exceeded", … }`	Request would exceed your monthly credit pool. See Pricing & quotas.
`429`	`{ "error": "concurrency limit exceeded", … }`	Too many runs in flight.

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"
    },
    "engine": "analyse",
    "tookMs": 1840,
    "executionId": "ex_…"
  }
]

/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: fetch: "html", proxies, options.timeoutMs. Max 10 URLs, 3 credits each. Response is always an 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."
      }'