---
title: POST /analyse
description: Interpret a page — outline, summary, flags — via one LLM pass over fetched markdown. Not a CSS scrape.
---

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.

<Aside type="caution" title="Not scrape">
Do not send `actions` or `engine`. Analyse is not a CSS planner. Use [`POST /scrape`](/docs/api/scrape) when you need exact, re-runnable fields (title, price, link lists).
</Aside>

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

## Request

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

```ts
{
  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:

```ts
{
  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](/docs/api/executions).

## 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](/docs/pricing). |
| `429` | `{ "error": "concurrency limit exceeded", … }` | Too many runs in flight. |

## Example

```bash
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."
      }'
```

```json
[
  {
    "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](/docs/mcp).

## 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`.

```bash
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."
      }'
```