# Agent quickstart
Source: https://docs.prefetch.io/agent-quickstart

Paste one prompt into Claude Code, Cursor or another coding agent, and it sets Prefetch up for you: key, MCP connection or app code, and a first verified call.

Copy this prompt into your coding agent. It asks you for your API key, sets up Prefetch the way your project needs, and checks that a first call works.

```text Prompt for your coding agent theme={"theme":"css-variables"}
Set up the Prefetch API (https://prefetch.io) in this project.

Docs index: https://docs.prefetch.io/llms.txt (full text: https://docs.prefetch.io/llms-full.txt).
Read only the pages you need.

1. Ask me for my Prefetch API key. I get it from https://prefetch.io/dashboard.
   Never print it, log it, or commit it.
2. Store it as PREFETCH_API_KEY: in .env for application code (make sure .env is in .gitignore),
   or in this agent's MCP config if I only want to use Prefetch from chat.
3. Ask me which I want, then do it:
   a. MCP for this agent: add the remote MCP server https://api.prefetch.io/mcp
      (Claude Code: `claude mcp add --transport http prefetch https://api.prefetch.io/mcp`,
      then authenticate from /mcp; Cursor: add it to .cursor/mcp.json).
   b. Application code: call the REST API with the X-API-Key header. There is no SDK; use the
      project's existing HTTP client. Every response is {success, data, meta}; on failure branch
      on error_code and retry only when retryable is true.
4. Verify: call GET https://api.prefetch.io/classify?url=https://stripe.com (5 credits) and
   show me data.classification.category.
5. Tell me what you changed, and link the docs pages for the endpoints I'm likely to use.
```

## What the agent will do

**1. Ask for your key**

Agents can't sign up for you. Create a key on the [dashboard](https://prefetch.io/dashboard) and paste it when asked.

**2. Pick a setup**

**MCP** gives the agent Prefetch tools in chat: scrape, enrich, crawl, monitor and more. **App code** adds REST calls to your project. See [MCP server](/mcp/overview) and the [API reference](/api-reference/introduction).

**3. Verify**

One `/classify` call proves the key and the connection work. It costs 5 credits.

## Docs for agents

* [`llms.txt`](https://docs.prefetch.io/llms.txt): an index of every page.
* [`llms-full.txt`](https://docs.prefetch.io/llms-full.txt): every page in one file.
* Every page has a menu to copy it as markdown, or open it in Claude, ChatGPT or Cursor.

## Next

> [card] [MCP server](/mcp/overview)
>
> Connect Claude, ChatGPT, Cursor or any MCP client.

> [card] [Recipes](/recipes/overview)
>
> Each recipe has a prompt you can hand to your agent.


# POST /batch/{endpoint}
Source: https://docs.prefetch.io/api-reference/endpoint/batch

POST /batch/{endpoint}
Run brand, enrich, company, classify, screenshot or styleguide on up to 500 URLs as one job. Free to submit.

Starts a batch of one endpoint and returns `202` with a job id. Read results with [`GET /batch/{endpoint}/{id}`](/api-reference/endpoint/batch-status).

**Free to submit.** Each URL answered costs what one call of that endpoint costs. Failed requests are never charged.

> [card] [Guide: Batches](/jobs/batches)
>
> Options, results, webhooks, credits and examples.


# DELETE /batch/{endpoint}/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/batch-cancel

DELETE /batch/{endpoint}/{id}
Stop a running batch. URLs already answered stay readable, and are charged.

## Overview

Stops a running batch: no new URLs are started, and the ones in flight finish. URLs already answered stay readable from [`GET /batch/{endpoint}/{id}`](/api-reference/endpoint/batch-status) until the batch expires, and are charged as usual. Cancelling a batch that already finished returns its final state.

```bash theme={"theme":"css-variables"}
curl -X DELETE "https://api.prefetch.io/batch/enrich/crw_7c2e9a4b1d0f4e6a8b3c5d7e9f1a2b3c" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```


# GET /batch/{endpoint}/{id}/errors
Source: https://docs.prefetch.io/api-reference/endpoint/batch-errors

GET /batch/{endpoint}/{id}/errors
The URLs of a batch that failed, with their error codes. Free.

## Overview

Lists the URLs that were run and failed, oldest first, each with an `error_code`, the same code a single call of that URL would have answered with, so you can tell the ones worth retrying (`TARGET_TIMEOUT`, `TARGET_SERVER_ERROR`) from the ones that never will work (`DNS_RESOLUTION_FAILED`, `TARGET_BLOCKED`). Free; failed URLs are never charged.

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/batch/enrich/crw_7c2e9a4b1d0f4e6a8b3c5d7e9f1a2b3c/errors" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```


# POST /batch/scrape
Source: https://docs.prefetch.io/api-reference/endpoint/batch-scrape

POST /batch/scrape
Scrape up to 500 URLs as one job. Free to submit, then 1 credit per page.

Starts a batch scrape and returns `202` with a job id. Read the pages with [`GET /batch/scrape/{id}`](/api-reference/endpoint/batch-scrape-status).

**Free to submit.** 1 credit per page returned, 4 with `summary`, `json` or `check_prompt_injection`. Failed requests are never charged.

> [card] [Guide: Batches](/jobs/batches)
>
> Options, results, webhooks, credits and examples.


# DELETE /batch/scrape/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/batch-scrape-cancel

DELETE /batch/scrape/{id}
Stop a running batch scrape. Pages already scraped stay readable. Free.

## Overview

Stops a batch that is `pending` or `running`. Pages already scraped stay readable through [`GET /batch/scrape/{id}`](/api-reference/endpoint/batch-scrape-status) until the batch expires, and are billed on the next status call as usual. Cancelling a finished batch returns its final state. Free.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl -X DELETE "https://api.prefetch.io/batch/scrape/crw_5a8d2e7f1c4b4a9e8d3c6b1a0f9e8d7c" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```


# GET /batch/scrape/{id}/errors
Source: https://docs.prefetch.io/api-reference/endpoint/batch-scrape-errors

GET /batch/scrape/{id}/errors
The pages of a batch scrape that failed, with error codes, and the URLs it skipped. Free.

## Overview

The pages of a batch that were fetched and failed, oldest first, each with an [`error_code`](/concepts/errors#error-codes), plus `skipped`: pages left out, by reason: for a batch, `duplicate` when a URL redirected onto a page the batch already had, or `blocklist` when a URL was added to your blocklist after you submitted. The same response as [`GET /crawl/{id}/errors`](/api-reference/endpoint/crawl-errors). Free.

Use the codes to decide what to resubmit: `TARGET_TIMEOUT` and `TARGET_SERVER_ERROR` often succeed on a second try, `DNS_RESOLUTION_FAILED` and `TARGET_CLIENT_ERROR` will not.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/batch/scrape/crw_5a8d2e7f1c4b4a9e8d3c6b1a0f9e8d7c/errors" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```


# GET /batch/scrape/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/batch-scrape-status

GET /batch/scrape/{id}
Poll a batch scrape for progress and read its pages. Charges 1 credit for each page completed since your last call.

## Overview

The same response as [`GET /crawl/{id}`](/api-reference/endpoint/crawl-status), with `kind: "batch"`: progress, plus a page of scraped pages in completion order. Follow `next` until it is `null` to read every page. Results stay readable until `expires_at`, **24 hours** after the batch was created.

Each page carries `ok`. A failed page has `ok: false`, an `error`, and an [`error_code`](/concepts/errors#error-codes), and is not charged.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/batch/scrape/crw_5a8d2e7f1c4b4a9e8d3c6b1a0f9e8d7c" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```


# GET /batch/{endpoint}/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/batch-status

GET /batch/{endpoint}/{id}
Progress and results of a batch, a page at a time. Each answered URL carries what a single call returns.

## Overview

Returns the batch's progress and a page of answered URLs, in completion order. Each item carries every field the single endpoint returns for that URL (`domain`, `brand`, `company`, `classification`, `screenshot_url`, `styleguide`…), plus the batch's own bookkeeping:

| Field | Meaning |
| - | - |
| `ok` | `false` when the URL could not be answered. You are not charged for it. |
| `error`, `error_code` | Why, as one of the API's [error codes](/concepts/errors). |
| `status_code` | 200 for an answered URL. |

Follow `next` until it is `null` to read every result. Results stay readable until `expires_at`, 24 hours after the batch was created.

## Example request

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/batch/enrich/crw_7c2e9a4b1d0f4e6a8b3c5d7e9f1a2b3c?limit=50" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "crw_7c2e9a4b1d0f4e6a8b3c5d7e9f1a2b3c",
    "status": "completed",
    "kind": "batch",
    "endpoint": "enrich",
    "url": "https://stripe.com",
    "total": 3,
    "completed": 3,
    "failed": 0,
    "credits_used": 36,
    "created_at": "2026-10-13T09:14:03.221Z",
    "started_at": "2026-10-13T09:14:04.010Z",
    "finished_at": "2026-10-13T09:14:41.512Z",
    "expires_at": "2026-10-14T09:14:03.221Z",
    "error": null,
    "next": null,
    "data": [
      {
        "url": "https://stripe.com",
        "depth": 0,
        "status_code": 200,
        "ok": true,
        "error": null,
        "error_code": null,
        "domain": "stripe.com",
        "brand": { "colors": { "brand_colors": [{ "color": "rgb(99, 91, 255)", "hex": "#635BFF", "name": "Medium Slate Blue" }] } },
        "company": { "name": "Stripe, Inc.", "emails": [], "addresses": [] },
        "classification": { "iab_id": "IAB3-4", "category": "Business" }
      }
    ]
  },
  "meta": { "requestId": "2e3d4c5b-6a7f-4b8c-9d0e-1f2a3b4c5d6e", "durationMs": 88 }
}
```

## Credits

Polling is free in itself: each call charges only the URLs that completed since the previous call, at the endpoint's own price, and whatever no call claimed is charged when the batch ends. Polling every five seconds costs exactly what polling once at the end does.


# GET /brand
Source: https://docs.prefetch.io/api-reference/endpoint/brand

GET /brand
Colors, logos, fonts, images and social links for any website. 10 credits.

Returns a site's brand assets under `data.brand`. Parameters are camelCase, like `screenshotColors`.

**10 credits.** Failed requests are never charged.

> [card] [Guide: Brand](/company-data/brand)
>
> Every color option, design tokens, the response fields and examples.


# GET /classify
Source: https://docs.prefetch.io/api-reference/endpoint/classify

GET /classify
Put a website into an IAB category, with descriptions, stock tickers and ISINs. 5 credits.

Returns the site's IAB category and subcategory under `data.classification`.

**5 credits.** Failed requests are never charged.

> [card] [Guide: Classify](/company-data/classify)
>
> IAB IDs, the description fields and examples.


# GET /company
Source: https://docs.prefetch.io/api-reference/endpoint/company

GET /company
Legal name, contact emails, addresses and key pages for the company behind a website. 5 credits.

Returns the organization behind a site under `data.company`.

**5 credits.** Failed requests are never charged.

> [card] [Guide: Company](/company-data/company)
>
> Every field, curated and live answers, and examples.


# POST /crawl
Source: https://docs.prefetch.io/api-reference/endpoint/crawl

POST /crawl
Crawl a site, or a section of it, and get every page as markdown. Free to submit, then 1 credit per page.

Starts a crawl and returns `202` with a crawl id. Read the pages with [`GET /crawl/{id}`](/api-reference/endpoint/crawl-status).

**Free to submit.** 1 credit per page returned, 4 with `summary`, `json` or `check_prompt_injection`. Failed requests are never charged.

> [card] [Guide: Crawl a site](/web-data/crawl)
>
> Scope, sitemap seeding, politeness, webhooks and examples.


# DELETE /crawl/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/crawl-cancel

DELETE /crawl/{id}
Stop a running crawl. Pages already fetched stay readable. Free.

## Overview

Stops a crawl that is `pending` or `running`. The worker notices within a few pages and stops fetching.

Nothing is thrown away: pages already crawled stay readable through [`GET /crawl/{id}`](/api-reference/endpoint/crawl-status) until the crawl expires, 24 hours after it was created. They are billed on the next status call as usual, so you pay for what was fetched and nothing more.

Cancelling is free.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl -X DELETE "https://api.prefetch.io/crawl/crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch(
  `https://api.prefetch.io/crawl/${crawlId}`,
  { method: "DELETE", headers: { "X-API-Key": process.env.PREFETCH_API_KEY } }
);
const { data } = await res.json();
console.log(data.status); // "cancelled"
```

```python Python theme={"theme":"css-variables"}
import requests, os

r = requests.delete(
    f"https://api.prefetch.io/crawl/{crawl_id}",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
print(r.json()["data"]["status"])  # "cancelled"
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e",
    "status": "cancelled",
    "url": "https://docs.stripe.com",
    "total": 38,
    "completed": 12,
    "failed": 1,
    "credits_used": 36,
    "created_at": "2026-08-20T09:14:03.221Z",
    "started_at": "2026-08-20T09:14:04.010Z",
    "finished_at": "2026-08-20T09:16:41.882Z",
    "expires_at": "2026-08-21T09:14:03.221Z",
    "error": null
  },
  "meta": {
    "requestId": "e7b6a5f4-bd0e-4f70-c15c-4d6e8f0a2b43",
    "durationMs": 61
  }
}
```

## Behavior

* **Already finished?** Cancelling a `completed`, `failed`, or `cancelled` crawl is a no-op. You get `200` with the crawl's real final state rather than an error.
* **Not yet started?** The queued job is removed, so no pages are ever fetched.
* **Unknown or expired id?** `404`.

A crawl you do not own also returns `404` rather than `403`. Crawl ids are unguessable, and confirming that some id exists is the only thing an enumeration attempt is after.

## Related

> [card] [POST /crawl](/api-reference/endpoint/crawl)
>
> Start a crawl.

> [card] [GET /crawl/\{id}](/api-reference/endpoint/crawl-status)
>
> Read progress and results.


# GET /crawl/{id}/errors
Source: https://docs.prefetch.io/api-reference/endpoint/crawl-errors

GET /crawl/{id}/errors
Why a crawl returned fewer pages than expected: failed pages with error codes, and skipped URLs by reason. Free.

## Overview

Explains a crawl that came back smaller than you expected. It returns two things:

* **`failed`**: pages that were fetched and failed, oldest first, each with an [`error_code`](/concepts/errors#error-codes). Paged with `skip` and `limit`; follow `next` until it is `null`.
* **`skipped`**: every URL the crawl found but did not fetch, counted by reason, with a few example URLs for each.

| Reason | Meaning |
| - | - |
| `limit` | The crawl had already queued `limit` pages. |
| `depth` | Deeper than `max_depth`. |
| `out-of-scope` | Above the start URL's path. Set `crawl_entire_domain` to follow these. |
| `excluded` | Matched `exclude_paths`. |
| `not-included` | Matched none of `include_paths`. |
| `robots` | Disallowed by the site's `robots.txt`. |
| `off-site` | On another site or a subdomain you did not allow. |
| `file` | A file rather than a page: an image, an archive, a stylesheet. |
| `invalid` | Not a URL the API will fetch, such as a private address. |
| `blocklist` | On your key's blocklist. |
| `duplicate` | A page the crawl already had, under another URL or through a redirect. |

Works while the crawl is running and until it expires. Free.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/crawl/crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e/errors" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

## Related

> [card] [POST /crawl](/api-reference/endpoint/crawl)
>
> Start a crawl.

> [card] [Error handling](/concepts/errors)
>
> What each error code means, and which are worth retrying.


# GET /crawl/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/crawl-status

GET /crawl/{id}
Poll a crawl for progress and read its pages. Charges 1 credit for each page completed since your last call.

## Overview

Returns where a crawl has got to, plus a page of results in completion order. Poll it until `status` is `completed`.

Results are paginated. Each response carries a `next` link; follow it until `next` is `null` to read every page. Results stay readable until `expires_at`, **24 hours** after the crawl was created. See [Async jobs](/concepts/async-jobs).

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/crawl/crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const id = "crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e";
const headers = { "X-API-Key": process.env.PREFETCH_API_KEY };

// Poll until the crawl finishes, then read every page of results.
let status;
do {
  await new Promise((r) => setTimeout(r, 5000));
  const res = await fetch(`https://api.prefetch.io/crawl/${id}`, { headers });
  ({ data: status } = await res.json());
  console.log(`${status.completed}/${status.total} pages`);
} while (status.status === "pending" || status.status === "running");

const pages = [...status.data];
let next = status.next;
while (next) {
  const res = await fetch(`https://api.prefetch.io${next}`, { headers });
  const { data } = await res.json();
  pages.push(...data.data);
  next = data.next;
}
console.log(`${pages.length} pages collected`);
```

```python Python theme={"theme":"css-variables"}
import os, time, requests

crawl_id = "crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e"
headers = {"X-API-Key": os.environ["PREFETCH_API_KEY"]}
base = "https://api.prefetch.io"

while True:
    data = requests.get(f"{base}/crawl/{crawl_id}", headers=headers).json()["data"]
    print(f"{data['completed']}/{data['total']} pages")
    if data["status"] not in ("pending", "running"):
        break
    time.sleep(5)

pages, nxt = list(data["data"]), data["next"]
while nxt:
    data = requests.get(base + nxt, headers=headers).json()["data"]
    pages.extend(data["data"])
    nxt = data["next"]
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e",
    "status": "running",
    "url": "https://docs.stripe.com",
    "total": 38,
    "completed": 12,
    "failed": 1,
    "credits_used": 36,
    "created_at": "2026-08-20T09:14:03.221Z",
    "started_at": "2026-08-20T09:14:04.010Z",
    "finished_at": null,
    "expires_at": "2026-08-21T09:14:03.221Z",
    "error": null,
    "next": "/crawl/crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e?skip=25&limit=25",
    "data": [
      {
        "url": "https://docs.stripe.com/payments",
        "depth": 0,
        "status_code": 200,
        "ok": true,
        "error": null,
        "final_url": "https://docs.stripe.com/payments",
        "domain": "docs.stripe.com",
        "metadata": {
          "title": "Payments",
          "description": "Accept payments online.",
          "language": "en"
        },
        "markdown": {
          "content": "# Payments\n\nAccept payments online, in person, and around the world...",
          "char_count": 2841,
          "word_count": 402,
          "truncated": false,
          "main_content_only": true
        }
      }
    ]
  },
  "meta": {
    "requestId": "d6a5f4e3-ac9d-4e6f-b04b-3c5d7e9f1a32",
    "durationMs": 96
  }
}
```

## Statuses

| Status | Meaning |
| - | - |
| `pending` | Queued, not started. |
| `running` | In progress. `data` already holds the pages finished so far. |
| `completed` | Finished. |
| `failed` | Stopped early. See `error`. Pages already stored are still readable. |
| `cancelled` | You called `DELETE /crawl/{id}`. |

> [!NOTE]
>
> `total` is the frontier size **as currently known**, not a final count. A crawl discovers pages as it goes, so this number rises until the frontier is exhausted or `limit` is reached. Do not treat `completed === total` as "finished": check `status`.

## Page objects

Each entry in `data` carries the crawl's bookkeeping plus the same fields `GET /scrape` returns for that page:

| Field | Meaning |
| - | - |
| `url` | The page that was crawled. |
| `depth` | How many links from the start URL. Sitemap-seeded pages are `0`. |
| `ok` | `false` when the page could not be fetched. |
| `error` | Why it failed, when `ok` is `false`. |
| `status_code`, `metadata`, `markdown`, … | Exactly as in [`GET /scrape`](/api-reference/endpoint/scrape), shaped by `scrape_options`. |

Failed pages are listed rather than silently dropped, so you can see what a crawl could not reach. You are not charged for them.

## Billing

This endpoint is where crawled pages are charged: each call bills for the pages that completed **since your previous call**, at 1 credit each (4 when the crawl asked for `summary` or `json`).

That makes polling safe: calling it ten times while a crawl runs costs exactly the same as calling it once at the end. `credits_used` on the response shows the running total for the crawl.

## Related

> [card] [POST /crawl](/api-reference/endpoint/crawl)
>
> Start a crawl and configure its scope.

> [card] [DELETE /crawl/\{id}](/api-reference/endpoint/crawl-cancel)
>
> Stop a running crawl. Free.


# GET /enrich
Source: https://docs.prefetch.io/api-reference/endpoint/enrich

GET /enrich
Brand, company and IAB classification for a domain in one request. 12 credits.

Returns `data.brand`, `data.company` and `data.classification` in one call, for less than the three endpoints cost separately. Parameters are camelCase, like `/brand`.

**12 credits.** Failed requests are never charged.

> [card] [Guide: Enrich a company](/company-data/enrich)
>
> A full real response, curated and live answers, and examples.


# GET /health
Source: https://docs.prefetch.io/api-reference/endpoint/health

GET /health
Check that the Prefetch API is up. No API key needed, and free.

Returns `200` with `{"status": "ok"}` while the API is running. It needs no API key and costs nothing, so you can point your own uptime monitoring at it.

```bash theme={"theme":"css-variables"}
curl https://api.prefetch.io/health
```

```json theme={"theme":"css-variables"}
{ "status": "ok" }
```

For incidents and uptime history, see the [status page](https://prefetch.betteruptime.com/). For a check that also confirms Prefetch can accept background jobs, use [`GET /ready`](/api-reference/endpoint/ready).


# GET /logo/token
Source: https://docs.prefetch.io/api-reference/endpoint/logo-token

GET /logo/token
Your organization's publishable logo CDN token, with this month's quota and use.

## Overview

Returns the token to put in [logo CDN](/company-data/logo-cdn) URLs, an example URL, and this month's quota and use. Use counts reach it within a minute or so of the requests.

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/logo/token" -H "X-API-Key: $PREFETCH_API_KEY"
```

Free. Not available through RapidAPI.


# POST /logo/token/rotate
Source: https://docs.prefetch.io/api-reference/endpoint/logo-token-rotate

POST /logo/token/rotate
Replace your logo CDN token. Logos embedded with the old token stop loading at once.

## Overview

Issues a new publishable token for your organization and retires the old one immediately. Every logo already embedded with the old token stops loading, so rotate only when someone else is using your token against your quota, then update your pages with the new one.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/logo/token/rotate" -H "X-API-Key: $PREFETCH_API_KEY"
```

Free. Not available through RapidAPI.


# GET /map
Source: https://docs.prefetch.io/api-reference/endpoint/map

GET /map
List every URL a site exposes, from its sitemaps and on-page links. 1 credit.

Returns a site's URLs, most useful first, without fetching the pages.

**1 credit.** Failed requests are never charged.

> [card] [Guide: Map a site](/web-data/map)
>
> Ordering, search, sources, scope and examples.


# POST /monitor
Source: https://docs.prefetch.io/api-reference/endpoint/monitor

POST /monitor
Watch pages, sites and searches on a schedule, and get told what changed. Free to create; each check is billed per page.

Creates a monitor and returns `201` with its settings and webhook secret.

**Free to create.** Each check costs 1 credit per page fetched, plus extras. See [Limits and credits](/monitors/limits). Failed requests are never charged.

> [card] [Guide: Monitors](/monitors/overview)
>
> Targets, schedules, change detection, goals, alerts and limits.


# GET /monitor/{id}/checks/{checkId}
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-check

GET /monitor/{id}/checks/{checkId}
What one check found, page by page: status, diff, and the judge's verdict. Free.

## Overview

Returns one check with a page of its per-page results. Each page carries its status, a diff when it changed, the judge's verdict when the monitor has a goal, and, in json mode, the full current extraction.

Pass `status=changed` to see only the pages that changed. Results are paginated: follow `next` until it is `null`.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/monitor/mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c/checks/chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a?status=changed" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const url = `https://api.prefetch.io/monitor/${monitorId}/checks/${checkId}?status=changed`;
const res = await fetch(url, { headers: { "X-API-Key": process.env.PREFETCH_API_KEY } });
const { data: check } = await res.json();

for (const page of check.pages) {
  if (page.is_meaningful === false) continue; // the judge ruled it noise
  console.log(page.url, page.judgment?.reason);
  console.log(page.diff?.text ?? JSON.stringify(page.diff?.fields, null, 2));
}
```

```python Python theme={"theme":"css-variables"}
import os, requests

check = requests.get(
    f"https://api.prefetch.io/monitor/{monitor_id}/checks/{check_id}",
    params={"status": "changed"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
).json()["data"]

for page in check["pages"]:
    if page["is_meaningful"] is False:
        continue
    print(page["url"], (page["judgment"] or {}).get("reason"))
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a",
    "monitor_id": "mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c",
    "status": "completed",
    "trigger": "scheduled",
    "scheduled_for": "2026-10-12T06:00:00.000Z",
    "started_at": "2026-10-12T06:00:04.112Z",
    "finished_at": "2026-10-12T06:01:27.930Z",
    "estimated_credits": 55,
    "actual_credits": 24,
    "summary": { "total_pages": 19, "same": 16, "new": 1, "changed": 1, "removed": 1, "error": 0 },
    "target_results": [
      { "target_id": "tgt_8d1e0f2a3b4c5d6e", "type": "scrape", "pages": 1, "checked": 1, "baseline": false },
      { "target_id": "tgt_1a2b3c4d5e6f7a8b", "type": "crawl", "discovered": 17, "limit": 25, "complete": true, "baseline": false }
    ],
    "error": null,
    "notifications": {
      "webhook": { "pending": 0, "delivered": 2, "failed": 0 },
      "email": { "pending": 0, "sent": 1, "failed": 0 }
    },
    "pages": [
      {
        "target_id": "tgt_8d1e0f2a3b4c5d6e",
        "url": "https://example.com/pricing",
        "status": "changed",
        "status_code": 200,
        "error": null,
        "title": "Pricing | Example",
        "previous_check_id": "chk_51b0c2d3e4f5a6b7c8d9e0f1a2b3c4d5",
        "is_meaningful": true,
        "judgment": {
          "meaningful": true,
          "confidence": "high",
          "reason": "The Starter plan's price went from $19 to $24 a month.",
          "meaningful_changes": [
            { "type": "changed", "before": "$19/mo", "after": "$24/mo", "reason": "A plan price changed." }
          ]
        },
        "diff": {
          "fields": { "plans[0].price": { "previous": "$19/mo", "current": "$24/mo", "change": "changed" } },
          "changed_fields": 1
        },
        "snapshot": {
          "json": {
            "plans": [
              { "name": "Starter", "price": "$24/mo", "features": ["3 seats", "Email support"] },
              { "name": "Pro", "price": "$49/mo", "features": ["Unlimited seats", "SSO"] }
            ]
          }
        }
      }
    ],
    "next": null
  },
  "meta": {
    "requestId": "c5a8e9f0-1b2c-4d34-b5e6-708192a3b4c5",
    "durationMs": 74
  }
}
```

## Check statuses

| Status | Meaning |
| - | - |
| `queued` | Waiting for a worker. |
| `running` | In progress: `pages` already holds what it has recorded. |
| `completed` | Every page was checked. |
| `partial` | Some pages errored, or the check stopped early on credits or its 30-minute limit. Its results are real but incomplete: `error` says why. |
| `failed` | No page could be checked. |
| `skipped_overlap` | The previous check was still running when this one came due. |
| `skipped_no_credits` | The key that owns the monitor had no credits left, or was revoked. Never charged. |

## Reading a page

| Field | Meaning |
| - | - |
| `status` | `same`, `new`, `changed`, `removed` or `error`. See [detecting changes](/monitors/change-detection). |
| `diff.text`, `diff.hunks` | Markdown mode: the unified diff, and the same hunks as structured lines. |
| `diff.fields` | Json mode: each changed field by JSON path, with `previous`, `current` and `change` (`added`, `removed` or `changed`). |
| `diff.truncated` | The diff was larger than the stored cap. `added_lines` and `removed_lines` still count all of it. |
| `is_meaningful`, `judgment` | The judge's verdict and its reasoning. `null` when the page was not judged. |
| `snapshot.json` | Json mode: the full current extraction, so you never need to re-fetch the page. |
| `previous_check_id` | The check whose snapshot this one was compared with. |

A page that is new since the first check carries its whole content as an all-added diff. Removed pages carry no diff.

## Related

> [card] [GET /monitor/\{id}/checks](/api-reference/endpoint/monitor-checks)
>
> Find a check id.

> [card] [monitor.page webhook](/api-reference/endpoint/monitor-webhook-page)
>
> Get the same page objects pushed to you.


# GET /monitor/{id}/checks
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-checks

GET /monitor/{id}/checks
A monitor's check history, newest first. Free.

## Overview

Lists the monitor's checks, newest first, with each one's status, page counts and credits. Pass `status` to filter: `status=skipped_no_credits`, say, to see when a key ran dry. Open any check with [`GET /monitor/{id}/checks/{checkId}`](/api-reference/endpoint/monitor-check) to see its pages.

Checks are kept for the monitor's `retention_days` (30 by default) and deleted after that.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/monitor/mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c/checks?limit=10" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch(`https://api.prefetch.io/monitor/${monitorId}/checks?limit=10`, {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();
for (const c of data.checks) console.log(c.finished_at, c.status, c.summary.changed);
```

```python Python theme={"theme":"css-variables"}
import os, requests

data = requests.get(
    f"https://api.prefetch.io/monitor/{monitor_id}/checks",
    params={"limit": 10},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
).json()["data"]
for c in data["checks"]:
    print(c["finished_at"], c["status"], c["summary"]["changed"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "checks": [
      {
        "id": "chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a",
        "monitor_id": "mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c",
        "status": "completed",
        "trigger": "scheduled",
        "scheduled_for": "2026-10-12T06:00:00.000Z",
        "started_at": "2026-10-12T06:00:04.112Z",
        "finished_at": "2026-10-12T06:01:27.930Z",
        "estimated_credits": 55,
        "actual_credits": 24,
        "summary": { "total_pages": 19, "same": 16, "new": 1, "changed": 1, "removed": 1, "error": 0 },
        "target_results": [
          { "target_id": "tgt_8d1e0f2a3b4c5d6e", "type": "scrape", "pages": 1, "checked": 1, "baseline": false },
          { "target_id": "tgt_1a2b3c4d5e6f7a8b", "type": "crawl", "discovered": 17, "limit": 25, "complete": true, "baseline": false }
        ],
        "error": null,
        "created_at": "2026-10-12T06:00:00.513Z",
        "updated_at": "2026-10-12T06:01:27.930Z"
      }
    ],
    "total": 1,
    "next": null
  },
  "meta": {
    "requestId": "b4f7d8e9-0a1b-4c23-a4d5-6f708192a3b4",
    "durationMs": 44
  }
}
```

## Streaks

Monitors keep no failure counter. To find out how long something has been going on, count the leading run of a status: the list is newest first, so the checks at the top that share a status are the current streak, and the first check with a different status ends it.

`actual_credits` is what each check was charged. Here it's 24: 18 pages fetched at 1 credit, plus the 3-credit surcharge on the one page tracking `json`, plus 3 pages judged at 1. Skipped checks are never charged.

## Related

> [card] [GET /monitor/\{id}/checks/\{checkId}](/api-reference/endpoint/monitor-check)
>
> What one check found, page by page.

> [card] [POST /monitor/\{id}/run](/api-reference/endpoint/monitor-run)
>
> Run a check now.


# DELETE /monitor/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-delete

DELETE /monitor/{id}
Delete a monitor, its check history and its pending webhooks. Stops all future charges. Free.

## Overview

Deletes the monitor together with its checks, page snapshots and any webhook deliveries still pending. Nothing more is fetched or billed.

To stop a monitor for a while instead, pause it with [`PATCH /monitor/{id}`](/api-reference/endpoint/monitor-update): a paused monitor costs nothing and keeps its history.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl -X DELETE "https://api.prefetch.io/monitor/mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
await fetch(`https://api.prefetch.io/monitor/${monitorId}`, {
  method: "DELETE",
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
```

```python Python theme={"theme":"css-variables"}
import os, requests

requests.delete(
    f"https://api.prefetch.io/monitor/{monitor_id}",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": { "id": "mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c", "deleted": true },
  "meta": {
    "requestId": "f2d5b6c7-8e9f-4a01-82b3-4d5e6f708192",
    "durationMs": 33
  }
}
```

A check that is running when you delete the monitor stops at its next step and is not billed. Deletion cannot be undone.

## Related

> [card] [PATCH /monitor/\{id}](/api-reference/endpoint/monitor-update)
>
> Pause instead, and keep the history.

> [card] [GET /monitor](/api-reference/endpoint/monitor-list)
>
> Your remaining monitors.


# GET /monitor/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-get

GET /monitor/{id}
One monitor's settings, next run, credit estimate and last check. Free.

## Overview

Returns the monitor exactly as it runs: every target with its effective options, the schedule as cron, the next run, the webhook, including its signing `secret`, and the summary of the most recent check.

A monitor you do not own returns `404` rather than `403`. Monitor ids are unguessable, and confirming that some id exists is the only thing an enumeration attempt is after.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/monitor/mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch(`https://api.prefetch.io/monitor/${monitorId}`, {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data: monitor } = await res.json();
console.log(monitor.next_run_at, monitor.estimated_credits_per_month);
```

```python Python theme={"theme":"css-variables"}
import os, requests

monitor = requests.get(
    f"https://api.prefetch.io/monitor/{monitor_id}",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
).json()["data"]
print(monitor["next_run_at"], monitor["estimated_credits_per_month"])
```

## Reading the monitor

| Field | Meaning |
| - | - |
| `schedule.cron` | The schedule the monitor runs on. A phrase you submitted is kept in `schedule.text`. |
| `next_run_at` | When the next check starts. `null` while the monitor is paused. |
| `current_check_id` | The check running right now, if one is. |
| `targets` | What it watches. Every target has an `id` and every option its effective value. |
| `webhook.secret` | The key to [verify webhook signatures](/concepts/webhooks#verify-signatures) with. Treat it like a password. |
| `estimated_credits_per_check` | Upper bound: every page fetched, and judged if there is a goal. |
| `estimated_credits_per_month` | The per-check estimate times the runs in an average month. |
| `last_check_summary` | Page counts from the most recent check, with its id and status. |
| `thumbnail_url` | A screenshot of the first page the monitor watches (JPEG, 640 pixels wide), or `null` until it's taken. |

For a monitor's history, list its checks with [`GET /monitor/{id}/checks`](/api-reference/endpoint/monitor-checks).

## Related

> [card] [PATCH /monitor/\{id}](/api-reference/endpoint/monitor-update)
>
> Change it, pause it or resume it.

> [card] [GET /monitor/\{id}/checks](/api-reference/endpoint/monitor-checks)
>
> Its check history.


# GET /monitor
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-list

GET /monitor
List the monitors your API key owns, newest first. Free.

## Overview

Returns your monitors with their settings, next run, credit estimate and the summary of each one's last check. Results are paginated: follow `next` until it is `null`.

An API key sees only the monitors it created.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/monitor?limit=25" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/monitor", {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

for (const m of data.monitors) {
  const last = m.last_check_summary;
  console.log(m.name, m.status, last ? `${last.changed} changed` : "no check yet");
}
```

```python Python theme={"theme":"css-variables"}
import os, requests

data = requests.get(
    "https://api.prefetch.io/monitor",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
).json()["data"]

for m in data["monitors"]:
    print(m["name"], m["status"], m["next_run_at"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "monitors": [
      {
        "id": "mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c",
        "name": "Competitor pricing",
        "status": "active",
        "schedule": { "cron": "0 9 * * 1-5", "timezone": "Europe/Athens", "text": "every weekday at 9am" },
        "next_run_at": "2026-10-13T06:00:00.000Z",
        "last_run_at": "2026-10-12T06:00:04.112Z",
        "last_check_summary": {
          "check_id": "chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a",
          "status": "completed",
          "finished_at": "2026-10-12T06:01:27.930Z",
          "total_pages": 19, "same": 16, "new": 1, "changed": 1, "removed": 1, "error": 0
        },
        "...": "the rest of the monitor, as in GET /monitor/{id}"
      }
    ],
    "total": 1,
    "next": null
  },
  "meta": {
    "requestId": "c9a2e3f4-5b6c-4d7e-9f80-1a2b3c4d5e6f",
    "durationMs": 47
  }
}
```

## Related

> [card] [GET /monitor/\{id}](/api-reference/endpoint/monitor-get)
>
> One monitor in full.

> [card] [POST /monitor](/api-reference/endpoint/monitor)
>
> Create a monitor.


# POST /monitor/{id}/run
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-run

POST /monitor/{id}/run
Run a monitor's check now instead of waiting for its schedule. Billed like a scheduled check.

## Overview

Queues a check outside the schedule and returns it straight away, with status `queued`. The check runs within seconds; poll [`GET /monitor/{id}/checks/{checkId}`](/api-reference/endpoint/monitor-check) until its status is no longer `queued` or `running`.

Use it to take the first baseline right after creating a monitor, to check a page on demand, or to try a new goal. It works on paused monitors too, and does not move the schedule.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/monitor/mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c/run" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const base = "https://api.prefetch.io";
const headers = { "X-API-Key": process.env.PREFETCH_API_KEY };

const run = await fetch(`${base}/monitor/${monitorId}/run`, { method: "POST", headers });
const { data: queued } = await run.json();

// Wait for the check, then show only what changed.
let check;
do {
  await new Promise((r) => setTimeout(r, 3000));
  const res = await fetch(`${base}/monitor/${monitorId}/checks/${queued.id}?status=changed`, { headers });
  ({ data: check } = await res.json());
} while (check.status === "queued" || check.status === "running");

for (const page of check.pages) console.log(page.url, page.diff?.text ?? page.diff?.fields);
```

```python Python theme={"theme":"css-variables"}
import os, time, requests

base = "https://api.prefetch.io"
headers = {"X-API-Key": os.environ["PREFETCH_API_KEY"]}

queued = requests.post(f"{base}/monitor/{monitor_id}/run", headers=headers).json()["data"]

while True:
    time.sleep(3)
    check = requests.get(
        f"{base}/monitor/{monitor_id}/checks/{queued['id']}",
        params={"status": "changed"},
        headers=headers,
    ).json()["data"]
    if check["status"] not in ("queued", "running"):
        break

for page in check["pages"]:
    print(page["url"], page["diff"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "chk_8e2d4f6a1b3c4d5e6f7a8b9c0d1e2f3a",
    "monitor_id": "mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c",
    "status": "queued",
    "trigger": "manual",
    "scheduled_for": null,
    "started_at": null,
    "finished_at": null,
    "estimated_credits": 55,
    "actual_credits": 0,
    "summary": { "total_pages": 0, "same": 0, "new": 0, "changed": 0, "removed": 0, "error": 0 },
    "target_results": null,
    "error": null,
    "created_at": "2026-10-09T10:05:00.000Z",
    "updated_at": "2026-10-09T10:05:00.000Z"
  },
  "meta": {
    "requestId": "a3e6c7d8-9f0a-4b12-93c4-5e6f708192a3",
    "durationMs": 38
  }
}
```

The status is `202 Accepted`: the check has been queued, not run.

## One check at a time

A monitor runs one check at a time. If one is already queued or running, this returns `409` and names it: wait for it to finish rather than retrying in a loop. The same rule applies to scheduled checks: one that comes due while the previous is still running is recorded as `skipped_overlap` instead of running alongside it.

## Credits

A manual check is billed exactly like a scheduled one: 1 credit per page fetched (4 on targets tracking `json`), plus 1 per changed page judged against the goal. `estimated_credits` is the upper bound; `actual_credits` on the finished check is what was charged.

## Related

> [card] [GET /monitor/\{id}/checks/\{checkId}](/api-reference/endpoint/monitor-check)
>
> Read the check's results.

> [card] [POST /monitor](/monitors/overview)
>
> How monitors detect and report changes.


# PATCH /monitor/{id}
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-update

PATCH /monitor/{id}
Change a monitor, its schedule, goal, targets, webhook or email alerts, or pause and resume it. Free.

## Overview

Send only the fields you want to change; everything else stays as it is. The response is the updated monitor.

## Pause and resume

```json theme={"theme":"css-variables"}
{ "status": "paused" }
```

A paused monitor keeps its settings and history but runs no scheduled checks, so it costs nothing. Set `"status": "active"` to resume. The next check runs at the next scheduled time: runs missed while paused are not replayed. A check can still be run by hand while paused, with [`POST /monitor/{id}/run`](/api-reference/endpoint/monitor-run).

## Example request

```bash cURL theme={"theme":"css-variables"}
curl -X PATCH "https://api.prefetch.io/monitor/mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "schedule": { "text": "every 2 hours" },
    "goal": "Alert me when the Pro plan price changes"
  }'
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch(`https://api.prefetch.io/monitor/${monitorId}`, {
  method: "PATCH",
  headers: {
    "X-API-Key": process.env.PREFETCH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ status: "paused" }),
});
const { data } = await res.json();
console.log(data.status, data.next_run_at); // "paused" null
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.patch(
    f"https://api.prefetch.io/monitor/{monitor_id}",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
    json={"status": "active"},
)
print(r.json()["data"]["next_run_at"])
```

## What each field does

| Field | Effect |
| - | - |
| `name`, `retention_days` | Replaced. |
| `schedule` | Replaced; the next run is recalculated. |
| `goal` | Replaced. Setting a goal turns judging on; `null` clears it and turns judging off. |
| `judge_enabled` | Turns judging on or off without touching the goal. |
| `targets` | Replaces the **whole list**. See below. |
| `webhook` | Replaced. The signing secret is kept unless you send a new `secret` or `"rotate_secret": true`. `null` removes the webhook. |
| `email` | `to` replaces the list of addresses. Addresses you keep keep their status; new ones are confirmed as on create. `"resend_confirmation": true` emails pending addresses their confirmation again. `null` removes every address. |
| `status` | `active` or `paused`. |

## Changing targets

Each target keeps its own snapshots, so what you get on the next check depends on whether a target is still the same target:

* A target you send with its existing `id` keeps its snapshots.
* A target without an `id` that watches **the same URLs** as an existing one inherits that target's id, and its snapshots, automatically. Changing only its options, such as adding `exclude_selectors`, keeps its history.
* Any other target is new. Its first check is a silent baseline: every page is `new`, and nothing is announced.

Snapshots of targets you leave out are deleted.

> [!NOTE]
>
> Changing what a target compares (its selectors, or switching it to json mode) can make the next check report pages as `changed` once, because the old snapshot was taken the old way. From the check after that, the comparison is like for like again.

## Rotating the signing secret

```json theme={"theme":"css-variables"}
{ "webhook": { "url": "https://you.example.org/hooks/prefetch", "rotate_secret": true } }
```

The new secret is in the response, and applies to every delivery from then on, including retries of events queued before the change.

## Related

> [card] [GET /monitor/\{id}](/api-reference/endpoint/monitor-get)
>
> The monitor as it now runs.

> [card] [DELETE /monitor/\{id}](/api-reference/endpoint/monitor-delete)
>
> Delete it for good.


# monitor.check.completed webhook
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-webhook-check

WEBHOOK monitor.check.completed
POSTed to your webhook once per check, with its status and page counts.

## When it is sent

Once for every check that ran (`completed`, `partial` or `failed`), with the check's summary counts and what it was charged.

It is also sent once when a monitor **starts** being skipped for lack of credits (`skipped_no_credits`), so you hear that checks have stopped. It is not repeated for every skipped check after that, and checks skipped because the previous one was still running (`skipped_overlap`) send nothing.

`success` is `true` only for a `completed` check. For a `partial` or `failed` check, `data.error` says why.

To receive only this event and not one per page, set the monitor's webhook `events` to `["monitor.check.completed"]`.

## Responding

Answer with any `2xx` within **10 seconds**; failures are retried after 1, 5 and 15 minutes. The request is signed exactly like [`monitor.page`](/concepts/webhooks#verify-signatures): verify it the same way.

## Reading the page results

The event carries counts, not pages. To see what changed, fetch the check:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/monitor/$MONITOR_ID/checks/$CHECK_ID?status=changed" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

`monitor_id` and `check_id` are both in the event.

## Related

> [card] [monitor.page](/api-reference/endpoint/monitor-webhook-page)
>
> One event per changed page, with its diff.

> [card] [GET /monitor/\{id}/checks/\{checkId}](/api-reference/endpoint/monitor-check)
>
> Everything a check found.


# monitor.page webhook
Source: https://docs.prefetch.io/api-reference/endpoint/monitor-webhook-page

WEBHOOK monitor.page
Posted to your webhook for each page that changed, appeared, was removed, or started failing.

## When it's sent

One event for each page that, in a check:

* **changed** since the previous check,
* is **new**, meaning it appeared since the monitor's first check,
* was **removed**: it answers 404 or 410, or a complete crawl no longer finds it,
* or **started failing**. A page that stays down sends one event, not one per check.

Two things are never sent: the first check's baseline, where every page is new, and changes the [judge](/monitors/goals) ruled not meaningful. Both are still recorded on the check.

`data` is the same page object [`GET /monitor/{id}/checks/{checkId}`](/api-reference/endpoint/monitor-check) returns: status, diff, judgment and, in json mode, the current extraction.

## Responding

Answer with any `2xx` within **10 seconds**. A timeout, a `4xx` or `5xx`, or a redirect is retried after **1, 5 and 15 minutes**, then marked failed. Do slow work after you respond.

Retries carry the same `id`, also sent as `X-Prefetch-Delivery`. Store the ids you've handled and skip repeats.

## Verify the signature

Every request carries an `X-Prefetch-Signature` header, signed with the monitor's `webhook.secret`. See [Verify signatures](/concepts/webhooks#verify-signatures) for the scheme and code in Node.js and Python.

## Headers

| Header | Value |
| - | - |
| `X-Prefetch-Event` | `monitor.page` |
| `X-Prefetch-Delivery` | The delivery id, the same as `id` in the body |
| `X-Prefetch-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>` |
| `User-Agent` | `Prefetch-Webhooks/1.0` |

Any `headers` you set on the monitor's webhook are sent as well.

## Related

> [card] [monitor.check.completed](/api-reference/endpoint/monitor-webhook-check)
>
> One event per check, with its counts.

> [card] [Monitor alerts](/monitors/alerts)
>
> Configure the webhook and email alerts.


# GET /ready
Source: https://docs.prefetch.io/api-reference/endpoint/ready

GET /ready
Check that the Prefetch API can accept requests and background jobs. No API key needed, and free.

Returns `200` when the API is ready to handle requests, including the queue that runs crawls, batches and monitor checks. It returns `503` when that queue is unavailable. It needs no API key and costs nothing.

```bash theme={"theme":"css-variables"}
curl https://api.prefetch.io/ready
```

```json 200 Ready theme={"theme":"css-variables"}
{ "status": "ok" }
```

```json 503 Not ready theme={"theme":"css-variables"}
{ "status": "error", "message": "Redis connection failed" }
```

To check only that the API is running, use [`GET /health`](/api-reference/endpoint/health).


# GET /resolve
Source: https://docs.prefetch.io/api-reference/endpoint/resolve

GET /resolve
Turn a company, brand or product name into its domain. 1 credit, 3 with a live lookup, 0 when nothing matches.

Turns a name into the domain of its official website, with a confidence score for each candidate.

**1 credit**, 3 when a live lookup runs, 0 when nothing matches. Failed requests are never charged.

> [card] [Guide: Resolve a name](/company-data/resolve)
>
> Confidence scores, live lookups, typeahead and examples in cURL, Node.js and Python.


# GET /scrape
Source: https://docs.prefetch.io/api-reference/endpoint/scrape

GET /scrape
Turn any page into markdown, a summary, structured JSON, links or images. 1 credit, 4 with a summary or JSON.

Fetches one URL and returns it in the formats you ask for. `POST /scrape` takes the same options as a JSON body, which is easier for `json_schema` and `headers`.

**1 credit**, +3 for `summary`, `json` or `check_prompt_injection`. Failed requests are never charged.

> [card] [Guide: Scrape](/web-data/scrape)
>
> Formats, main content, JSON extraction, PDFs, the prompt-injection check and examples.


# GET /screenshot
Source: https://docs.prefetch.io/api-reference/endpoint/screenshot

GET /screenshot
Capture a page, the full page or one element, on any device, in light or dark mode, as JPEG, PNG, WebP or PDF. 1 credit.

Captures a page and returns a hosted image URL.

**1 credit**, whatever the options. Failed requests are never charged.

> [card] [Guide: Screenshots](/web-data/screenshot)
>
> Devices, element captures, formats and examples.


# GET /search
Source: https://docs.prefetch.io/api-reference/endpoint/search

GET /search
Search the web and get each result's title, URL and snippet, optionally with every result page scraped. 2 credits per 10 results.

Runs a web search and returns ranked results, optionally scraping each result page in the same call. `POST /search` takes the same fields as a JSON body, with `scrape_options`.

**2 credits per 10 results**, plus what each scraped page costs. Failed requests are never charged.

> [card] [Guide: Search](/web-data/search)
>
> Narrowing a search, scraping results, partial failures and examples.


# GET /styleguide
Source: https://docs.prefetch.io/api-reference/endpoint/styleguide

GET /styleguide
A site's design system, plus CSS variables and a Tailwind theme. 10 credits.

Reads a site's design system from the rendered page and exports it as CSS custom properties and a Tailwind theme.

**10 credits.** Failed requests are never charged.

> [card] [Guide: Styleguide](/company-data/styleguide)
>
> How sites are read, the full response and examples.


# GET /transaction
Source: https://docs.prefetch.io/api-reference/endpoint/transaction

GET /transaction
Turn a card transaction descriptor into its merchant: name, website, logo, processor and location. 3 credits, 1 for a repeat.

Reads a bank statement line and returns the merchant behind it, or says it's a person, transfer, fee, ATM withdrawal or refund. `POST /transaction` takes the same fields as a JSON body.

**3 credits**, 1 for a line looked up in the last 7 days, +10 with `include_brand`. Failed requests are never charged.

> [card] [Guide: Card transactions](/company-data/transaction)
>
> How lines are parsed and resolved, the response fields, and examples.


# API reference
Source: https://docs.prefetch.io/api-reference/introduction

Base URL, authentication, the response envelope and the conventions every Prefetch endpoint shares.

Each endpoint page in this section lists every parameter and response field, with a playground you can call from the browser. For how an endpoint works, with examples in cURL, Node.js and Python, read its guide in the **Docs** tab.

## Base URL

```
https://api.prefetch.io
```

## Authentication

Every endpoint except `/health` and `/ready` needs an `X-API-Key` header:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/classify?url=https://example.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

See [Authentication](/concepts/authentication) for OAuth, bearer tokens and key errors.

## Response envelope

Every response has the same shape:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": { },
  "meta": {
    "requestId": "uuid-v4",
    "durationMs": 1234
  }
}
```

On failure, `success` is `false` and `data` is replaced by an error:

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": "The target URL could not be resolved. Please check the domain name.",
  "error_code": "DNS_RESOLUTION_FAILED",
  "retryable": false,
  "meta": {
    "requestId": "b9e1a2f3-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "durationMs": 412
  }
}
```

Branch on `error_code`, not on the wording of `error`, which can change. `retryable` tells you whether the same request can succeed later.

See [Error handling](/concepts/errors) for every code.

## Conventions

* **Parameters** are snake\_case (`only_main_content`), except on `/brand` and `/enrich`, which take camelCase (`screenshotColors`). Batches and MCP take snake\_case everywhere.
* **GET or POST:** `/scrape`, `/search` and `/transaction` accept the same fields as a query string on `GET` or a JSON body on `POST`. Use `POST` for nested options like `json_schema`, `headers` or `scrape_options`.
* **URLs** can omit the scheme. `stripe.com` means `https://stripe.com`.
* **Request bodies** can be up to 1 MB.
* **Time limits:** most requests finish within 55 seconds, or fail with `TIMEOUT`. Give your HTTP client at least 60.
* **Ids** carry a prefix: `crw_` for crawls and batches, `mon_` for monitors, `chk_` for monitor checks.

## Background jobs

Crawls, batches and monitor checks run in the background. `POST /crawl`, `POST /batch/scrape`, `POST /batch/{endpoint}` and `POST /monitor/{id}/run` return `202` with an id, and you read the results with the matching `GET`, or get them by [webhook](/concepts/webhooks). See [Async jobs](/concepts/async-jobs).

## Rate limits

Each plan limits how many requests can run at once, from 1 on Free to 500 on Scale. The Free plan also allows 30 requests a minute. Going over either returns `429`. See [Rate limits](/concepts/rate-limits).

## Credit costs

| Endpoint | Credits |
| - | - |
| `GET /resolve` | 1. 3 when a live lookup runs (`live=true`). 0 when nothing matches. |
| `GET /transaction` | 3. 1 for a line looked up in the last 7 days. +10 with `include_brand`. |
| `GET /enrich` | 12 |
| `GET /brand` | 10 |
| `GET /styleguide` | 10 |
| `GET /company` | 5 |
| `GET /classify` | 5 |
| `GET /scrape` | 1. +3 when you ask for `summary`, `json` or `check_prompt_injection`. |
| `GET /search` | 2 per 10 results, rounded up. Each result page scraped costs what `/scrape` costs. |
| `GET /map` | 1 |
| `GET /screenshot` | 1 |
| `POST /answers` | 10 in `fast` mode. 100 in `ultra` mode, the REST default. |
| `POST /crawl` | Free to submit. 1 per page returned, or 4 with `summary`, `json` or `check_prompt_injection`. |
| `POST /batch/scrape` | Free to submit. 1 per page returned, or 4 with `summary`, `json` or `check_prompt_injection`. |
| `POST /batch/{endpoint}` | Free to submit. Each URL answered costs what one call of that endpoint costs. |
| Monitor checks | 1 per page fetched, +3 when a `json` extraction runs, +1 per page judged against a goal. A search target costs 2 per search, +1 per new result read. |
| Logo CDN images | No credits. Each plan includes a monthly logo quota. |
| Everything else | Free: job status, errors and cancel calls, managing monitors, `/logo/token`, `/health` and `/ready`. |

You're only charged for successful requests. See [Credits](/concepts/credits).

## OpenAPI

The full spec is at [`/api-reference/openapi.json`](/api-reference/openapi.json). Use it to generate a client in your language.


# Changelog
Source: https://docs.prefetch.io/changelog

New endpoints, features and changes to the Prefetch API.

Dates are when each change was documented.

**November 4, 2026**

Monitors

* Every monitor now has a `thumbnail_url`: a 640-pixel-wide screenshot of the first page it watches, taken after you create the monitor and again when an edit changes that page.

**October 31, 2026**

Monitors, map, brand and company

* **Search targets for monitors.** Watch up to 5 web searches and hear about new results that match your goal. See [Targets](/monitors/targets#search-targets).
* **Automatic pausing.** A monitor whose every page fails for 10 checks in a row, over at least 24 hours, is paused and its recipients are told.
* **`/map` ranks results** most useful first, and the first 10 links carry their page's title and description. A map that finds nothing fails with `NO_LINKS_FOUND`, free.
* **`/brand`** returns the color each role uses on the page in `brand.colors.roles`, and finds social links in more places.
* **`/company`** returns the site's key pages in `links`: about, pricing, careers, contact, blog and docs.

**October 15, 2026**

Monitors

* Monitor limits now depend on your plan: shortest schedule, monitors per key, pages per check, history and email recipients. See [Limits and credits](/monitors/limits).

**October 13, 2026**

New endpoints

* [`/search`](/web-data/search): web search, optionally with every result page scraped.
* [`/transaction`](/company-data/transaction): the merchant behind a card transaction line.
* [`/styleguide`](/company-data/styleguide): a site's design system, with CSS and Tailwind exports.
* [`/batch/{endpoint}`](/jobs/batches): run brand, enrich, company, classify, screenshot or styleguide on up to 500 URLs as one job.
* [Logo CDN](/company-data/logo-cdn): any company's logo as an embeddable image, from a monthly quota instead of credits.
* [`/screenshot`](/web-data/screenshot) gains devices, element captures, dark mode, ad blocking and WebP.

**October 11, 2026**

Batch scrape and crawl errors

* [`/batch/scrape`](/jobs/batches): scrape up to 500 known URLs as one job.
* `GET /crawl/{id}/errors` explains a crawl that came back smaller than expected.
* Every error now carries a stable `error_code` and a `retryable` flag. See [Error handling](/concepts/errors).

**October 10, 2026**

OAuth

* Apps such as Claude and ChatGPT can sign you in with OAuth instead of an API key. See [Authentication](/concepts/authentication#oauth-for-apps).

**October 9, 2026**

Monitors and resolve

* [Monitors](/monitors/overview): watch pages and sites on a schedule, judge changes against a goal, and get them by webhook or email.
* [`/resolve`](/company-data/resolve): turn a company or brand name into its domain.

**August 22, 2026**

MCP server

* The [MCP server](/mcp/overview) at `https://api.prefetch.io/mcp` gives Claude, Cursor and other agents every Prefetch tool, with nothing to install.

**August 20, 2026**

Web data

* [`/scrape`](/web-data/scrape), [`/map`](/web-data/map) and [`/crawl`](/web-data/crawl): any page or site as clean markdown, summaries or structured JSON.


# Brand
Source: https://docs.prefetch.io/company-data/brand

Colors, logos, fonts, images, social links and design tokens for any website. 10 credits.

`/brand` returns a site's brand assets under `data.brand`:

* **Colors:** the brand palette, plus optional colors from a screenshot and from source code
* **Logos:** the primary logo, secondary candidates, favicon and app icons
* **Fonts:** the font families the site uses
* **Images:** the Open Graph and Twitter images, brand assets and a screenshot
* **Social links:** profile URLs, keyed by platform
* **Design tokens** (opt-in): what each color is for, the type, and button and input styles

`data.brand` is the same block [`/enrich`](/company-data/enrich) returns, so `data.brand.colors` reads the same from either one.

## Example requests

```bash Default theme={"theme":"css-variables"}
curl "https://api.prefetch.io/brand?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash With screenshot colors theme={"theme":"css-variables"}
curl "https://api.prefetch.io/brand?url=https://stripe.com&screenshotColors=6" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash Every color source theme={"theme":"css-variables"}
curl "https://api.prefetch.io/brand?url=https://stripe.com&screenshotColors=8&css=true&html=true&filterAchromatic=true" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/brand?url=https://stripe.com", {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

console.log(data.brand.colors.brand_colors[0].hex); // "#635BFF"
console.log(data.brand.logos.primary.url);
console.log(data.brand.fonts.families);             // ["Sohne Var", "SF Pro Display"]
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/brand",
    params={"url": "https://stripe.com"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
brand = r.json()["data"]["brand"]
print(brand["colors"]["brand_colors"][0]["hex"])  # "#635BFF"
print(brand["logos"]["primary"]["url"])
```

## Example response

A real response for `stripe.com`, shortened where marked with `…`:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "url": "https://stripe.com/",
    "brand": {
      "colors": {
        "brand_colors": [
          { "hex": "#635BFF", "name": "Medium Slate Blue", "type": "accent", "color": "rgb(99, 91, 255)" },
          { "hex": "#001020", "name": "Black", "type": "brand", "color": "rgb(0, 16, 32)" },
          { "hex": "#0A2540", "name": "Midnight Blue", "type": "dark", "color": "rgb(10, 37, 64)" },
          { "hex": "#F8F8F8", "name": "White Smoke", "type": "background", "color": "rgb(248, 248, 248)" },
          { "hex": "#FFFFFF", "name": "White", "type": "light", "color": "rgb(255, 255, 255)" }
        ]
      },
      "fonts": { "families": ["Sohne Var", "SF Pro Display"] },
      "logos": {
        "primary": { "url": "https://curated.prefetch.io/1fcd…/primary.svg", "type": "logo", "format": "svg", "background": "transparent" },
        "secondary": [
          { "url": "https://curated.prefetch.io/1fcd…/secondary_1.svg", "type": "logo", "format": "svg", "background": "transparent", "source_type": "logo" }
        ],
        "favicon_url": "https://curated.prefetch.io/1fcd…/favicon.png",
        "icon_url": "https://curated.prefetch.io/1fcd…/icon.svg",
        "apple_touch_icon": "https://curated.prefetch.io/1fcd…/apple_touch_icon.jpg"
      },
      "images": {
        "og_image": "https://curated.prefetch.io/1fcd…/og_image.jpg",
        "twitter_image": "https://curated.prefetch.io/1fcd…/og_image.jpg",
        "assets": [{ "url": "https://curated.prefetch.io/1fcd…/asset_1779921418029.jpg", "alt": null, "type": "banner", "width": null, "height": null }],
        "screenshot_url": "https://curated.prefetch.io/1fcd…/screenshot.jpg"
      },
      "social_links": {
        "twitter": "https://twitter.com/stripe",
        "linkedin": "https://linkedin.com/company/stripe",
        "facebook": "https://facebook.com/StripeHQ",
        "instagram": null,
        "youtube": "https://youtube.com/stripe",
        "github": "https://github.com/stripe",
        "tiktok": null
      }
    }
  },
  "meta": {
    "requestId": "d4e5f6a7-b8c9-0d1e-2f3a-4b5c6d7e8f9a",
    "durationMs": 288
  }
}
```

Each color carries `hex`, `color` (as `rgb()`) and a human-readable `name`, such as `Medium Slate Blue` or `midnightblue`. Curated answers also say how the brand uses each color in `type`: `accent`, `brand`, `dark`, `light` or `background`. The first entry is the main brand color.

> [!NOTE]
>
> Well-known brands are answered from curated data in milliseconds. Other sites are read live, which takes 5 to 20 seconds, and the fields can differ a little. Treat every field as optional.

## Color options

By default you get the brand palette. Add options to pull colors from more places:

| Parameter | Adds | Lands in |
| - | - | - |
| *(default)* | The logo's and favicon's colors, and the brand colors the page sets itself (`theme-color`, the header, the primary buttons). Chromatic colors first, white, black and greys after. | `brand.colors.brand_colors` |
| *(default)* | The color each role uses on the page: `primary` and `secondary` button fills, `background`, `text` and `link` | `brand.colors.roles` |
| `screenshotColors=6` | N dominant colors from a screenshot of the page (2–12) | `brand.colors.screenshot_colors` |
| `css=true` | Colors defined in stylesheets | `brand.colors.code_colors` |
| `html=true` | Colors defined in HTML attributes | `brand.colors.code_colors` |
| `javascript=true` | Colors defined in JavaScript | `brand.colors.code_colors` |
| `filterAchromatic=true` | Drops near-white, near-black and grey results | |

`css`, `html` and `javascript` all feed one `code_colors` map, keyed by the nearest named color rather than by source. Groups are ordered by how much the site uses them. Every spelling of one color (`#000`, `rgb(0,0,0)`, `rgba(0,0,0,.25)`) is one entry, and transparent values are left out.

Logo and favicon colors are the exact color most of their pixels have. When that's within ΔE 6 of a color the page renders, it snaps to the page's color, so a brand color the CSS sets (`#632CA6`) comes back as that hex rather than a near neighbor.

`social_links` come from the page's links, then its JSON-LD `sameAs`, `rel="me"` and Twitter card tags. If none of those name a profile, Prefetch reads the footer after scrolling it into view. Each link is the profile's plain URL, without tracking parameters.

`/brand` takes camelCase parameters. Batches and MCP take the snake\_case spelling (`screenshot_colors`).

## Design tokens

`brand_colors` tells you what a brand's colors are. `designTokens=true` tells you what each one is **for**, read from the page as it renders:

* **Colors by role:** `primary` (the most prominent button's fill), `secondary`, `background`, `text`, `heading` and `link`, plus whether the page is `light` or `dark`
* **Typography:** body and heading font stacks, weights, line height, and the h1 to h3 and body sizes
* **Components:** the primary and secondary button (fill, label color, border, radius, weight) and the first text input
* **`border_radius`:** the primary button's rounding, a good guide to the whole site's

The block lands at `brand.design_tokens`. It's best effort: a field the page gives no reliable answer for is `null`. Requests with `designTokens=true` are always read live, never from curated data.

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/brand?url=https://stripe.com&designTokens=true" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```json theme={"theme":"css-variables"}
"design_tokens": {
  "color_scheme": "light",
  "colors": { "primary": "#533AFD", "secondary": null, "background": "#FFFFFF", "text": "#50617A", "heading": "#061B31", "link": "#533AFD" },
  "typography": {
    "body": { "font_family": "sohne-var", "font_stack": ["sohne-var", "SF Pro Display", "sans-serif"], "font_size": "16px", "font_weight": 400, "line_height": null },
    "heading": { "font_family": "sohne-var", "font_stack": ["sohne-var", "SF Pro Display", "sans-serif"], "font_weight": 300 },
    "sizes": { "h1": "48px", "h2": "32px", "h3": "26px", "body": "16px" }
  },
  "components": {
    "button_primary": { "background": "#533AFD", "text_color": "#FFFFFF", "border_color": null, "border_radius": "4px", "font_weight": 400 },
    "button_secondary": { "background": null, "text_color": "#FFFFFF", "border_color": null, "border_radius": "4px", "font_weight": 400 },
    "input": null
  },
  "border_radius": "4px"
}
```

For a full design system with spacing, shadows and ready-to-use CSS and Tailwind exports, use [`/styleguide`](/company-data/styleguide).

## Next

> [card] [Logo CDN](/company-data/logo-cdn)
>
> Just need logos in your UI? Embed them without an API call.

> [card] [API reference](/api-reference/endpoint/brand)
>
> Every parameter, and a playground to try it.


# Classify
Source: https://docs.prefetch.io/company-data/classify

Put any website into an IAB category, with a description, tagline, stock tickers and ISINs. 5 credits.

`/classify` reads a website and assigns it an [IAB Content Taxonomy](https://www.iab.com/guidelines/content-taxonomy/) category. Everything sits under `data.classification`, the same key [`/enrich`](/company-data/enrich) uses:

* **Category and subcategory:** for example `Business` › `Business Software`
* **Descriptions:** a short description, a one-line tagline and a longer summary
* **Stock tickers and ISINs:** for public companies

Static pages are read with a fast fetch. A real browser is used only when the page needs JavaScript to show its content.

It's the cheapest way to answer "what kind of business is this?", for example to score leads against your ideal customer profile.

## Example requests

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/classify?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/classify?url=https://stripe.com", {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();
const { category, subcategory } = data.classification;
console.log(`${category} > ${subcategory}`); // "Business > Business Software"
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/classify",
    params={"url": "https://stripe.com"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
classification = r.json()["data"]["classification"]
print(f"{classification['category']} > {classification['subcategory']}")
```

## Example response

A real response for `stripe.com`, shortened where marked with `…`:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "url": "https://stripe.com/",
    "classification": {
      "iab_id": "IAB3-4",
      "iab_parent_id": "IAB3",
      "category": "Business",
      "subcategory": "Business Software",
      "description": "A payments and financial-technology platform that lets businesses accept and process online and in-person payments, manage billing and subscriptions, issue cards, and move money across borders via APIs and prebuilt tools. …",
      "tagline_description": "A developer-first payments and financial infrastructure platform for online and in-person commerce.",
      "long_description": "Stripe is a global technology company that provides infrastructure for online payments and financial services. …",
      "stock_tickers": [],
      "isins": []
    }
  },
  "meta": {
    "requestId": "a3f2c1d4-7b6e-4f2a-9c1d-8e3f2a1b4c5d",
    "durationMs": 196
  }
}
```

## IAB IDs

`iab_id` and `iab_parent_id` use the IAB Content Taxonomy 1.0 ID format. The parent is a category, and the child adds a hyphen and a number:

* `IAB3`: the parent category (Business)
* `IAB3-4`: the subcategory (Business Software)

Common parent categories include `IAB3` (Business), `IAB4` (Careers), `IAB13` (Personal Finance) and `IAB19` (Technology & Computing).

## Next

> [card] [Enrich a company](/company-data/enrich)
>
> Industry, brand and company details in one call. **12 credits.**

> [card] [API reference](/api-reference/endpoint/classify)
>
> Every parameter, and a playground to try it.


# Company
Source: https://docs.prefetch.io/company-data/company

Legal name, contact emails, addresses and key pages for the company behind a website. 5 credits.

`/company` finds the organization behind a website. It reads structured data (JSON-LD, schema.org), the footer, contact pages and other signals, and returns them under `data.company`:

* **Names:** the legal entity (`Stripe, Inc.`) and the name people use (`Stripe`)
* **Emails:** contact and support addresses
* **Addresses:** street, city, state, postal code and country, plus the address as written
* **Facts:** employee count, founding year and parent company, when known
* **Key pages:** the `about`, `pricing`, `careers`, `contact`, `blog` and `docs` pages the homepage links to

Static pages are read with a fast fetch. A real browser is used only when the page needs JavaScript.

## Example requests

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/company?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/company?url=https://stripe.com", {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

console.log(data.company.name);              // "Stripe, Inc."
console.log(data.company.emails);            // ["support@stripe.com"]
console.log(data.company.addresses[0].city); // "South San Francisco"
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/company",
    params={"url": "https://stripe.com"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
company = r.json()["data"]["company"]
print(company["name"])
print(company["addresses"][0]["raw"])
```

## Example response

A real response for `stripe.com`:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "url": "https://stripe.com/",
    "company": {
      "name": "Stripe, Inc.",
      "display_name": "Stripe",
      "parentCompany": null,
      "employeeCount": 8000,
      "foundedYear": 2010,
      "isNsfw": false,
      "emails": ["support@stripe.com"],
      "addresses": [
        {
          "raw": "South San Francisco, California, United States",
          "street": null,
          "city": "South San Francisco",
          "state": "California",
          "postal_code": null,
          "country": "United States"
        }
      ]
    }
  },
  "meta": {
    "requestId": "b9e1a2f3-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "durationMs": 204
  }
}
```

## Fields

| Field | Meaning |
| - | - |
| `name` | The legal or trading name. |
| `display_name` | The short name people use. |
| `parentCompany`, `employeeCount`, `foundedYear` | Company facts, or `null` when unknown. |
| `isNsfw` | Whether the site's content is not safe for work. |
| `emails` | Contact and support addresses found on the site. |
| `addresses` | Each address as written (`raw`) and split into `street`, `city`, `state`, `postal_code` and `country`. Any part can be `null`, and the list is often empty. Handle an address that arrives as a plain string too. |
| `social_links` | Profile URLs keyed by platform, when found. `/enrich` puts them here too. |
| `links` | The site's `about`, `pricing`, `careers`, `contact`, `blog` and `docs` pages, each `null` when the homepage links none. |

Well-known companies are answered from curated data in milliseconds, and curated answers can leave out `links` and `social_links`. Other sites are read live. Treat every field as optional.

## Next

> [card] [Enrich a company](/company-data/enrich)
>
> Company, brand and industry in one call. **12 credits.**

> [card] [API reference](/api-reference/endpoint/company)
>
> Every parameter, and a playground to try it.


# Enrich a company
Source: https://docs.prefetch.io/company-data/enrich

Brand assets, company details and IAB industry for any domain, in one request. 12 credits.

`/enrich` returns everything Prefetch knows about the company behind a URL: its [brand](/company-data/brand), its [company details](/company-data/company) and its [industry](/company-data/classify). The page is loaded once, so it costs less than calling the three separately.

| Approach | Credits | Requests |
| - | - | - |
| `/enrich` | 12 | 1 |
| `/brand` + `/company` + `/classify` | 20 | 3 |

Each block sits under the same key its own endpoint uses: `data.brand`, `data.company` and `data.classification`. Code written for `/brand` or `/classify` reads an `/enrich` response unchanged. The one difference is `social_links`, which sits on `data.company` here and on `data.brand` in `/brand`.

## Example requests

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/enrich?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash With screenshot colors and CSS theme={"theme":"css-variables"}
curl "https://api.prefetch.io/enrich?url=https://stripe.com&screenshotColors=6&css=true" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/enrich?url=https://stripe.com", {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

console.log(data.company.display_name);              // "Stripe"
console.log(data.classification.category);           // "Business"
console.log(data.brand.colors.brand_colors[0].hex);  // "#635BFF"
console.log(data.brand.logos.primary.url);
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/enrich",
    params={"url": "https://stripe.com"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
data = r.json()["data"]
print(data["company"]["display_name"])        # "Stripe"
print(data["classification"]["category"])     # "Business"
print(data["brand"]["logos"]["primary"]["url"])
```

## Example response

A real response for `stripe.com`, shortened where marked with `…`:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "url": "https://stripe.com/",
    "brand": {
      "colors": {
        "brand_colors": [
          { "hex": "#635BFF", "name": "Medium Slate Blue", "type": "accent", "color": "rgb(99, 91, 255)" },
          { "hex": "#0A2540", "name": "Midnight Blue", "type": "dark", "color": "rgb(10, 37, 64)" },
          { "hex": "#FFFFFF", "name": "White", "type": "light", "color": "rgb(255, 255, 255)" }
        ]
      },
      "fonts": { "families": ["Sohne Var", "SF Pro Display"] },
      "logos": {
        "primary": { "url": "https://curated.prefetch.io/1fcd…/primary.svg", "type": "logo", "format": "svg", "background": "transparent" },
        "secondary": [
          { "url": "https://curated.prefetch.io/1fcd…/secondary_1.svg", "type": "logo", "format": "svg", "background": "transparent", "source_type": "logo" }
        ],
        "favicon_url": "https://curated.prefetch.io/1fcd…/favicon.png",
        "icon_url": "https://curated.prefetch.io/1fcd…/icon.svg",
        "apple_touch_icon": "https://curated.prefetch.io/1fcd…/apple_touch_icon.jpg"
      },
      "images": {
        "og_image": "https://curated.prefetch.io/1fcd…/og_image.jpg",
        "twitter_image": "https://curated.prefetch.io/1fcd…/og_image.jpg",
        "assets": [{ "url": "https://curated.prefetch.io/1fcd…/asset_1779921418029.jpg", "alt": null, "type": "banner", "width": null, "height": null }],
        "screenshot_url": "https://curated.prefetch.io/1fcd…/screenshot.jpg"
      }
    },
    "company": {
      "name": "Stripe, Inc.",
      "display_name": "Stripe",
      "parentCompany": null,
      "employeeCount": 8000,
      "foundedYear": 2010,
      "isNsfw": false,
      "emails": ["support@stripe.com"],
      "addresses": [
        { "raw": "South San Francisco, California, United States", "street": null, "city": "South San Francisco", "state": "California", "postal_code": null, "country": "United States" }
      ],
      "social_links": {
        "twitter": "https://twitter.com/stripe",
        "linkedin": "https://linkedin.com/company/stripe",
        "facebook": "https://facebook.com/StripeHQ",
        "instagram": null,
        "youtube": "https://youtube.com/stripe",
        "github": "https://github.com/stripe",
        "tiktok": null
      }
    },
    "classification": {
      "iab_id": "IAB3-4",
      "iab_parent_id": "IAB3",
      "category": "Business",
      "subcategory": "Business Software",
      "description": "A payments and financial-technology platform that lets businesses accept and process online and in-person payments, manage billing and subscriptions, issue cards, and move money across borders via APIs and prebuilt tools. …",
      "tagline_description": "A developer-first payments and financial infrastructure platform for online and in-person commerce.",
      "long_description": "Stripe is a global technology company that provides infrastructure for online payments and financial services. It was founded in 2010 by Irish brothers Patrick and John Collison. …",
      "stock_tickers": [],
      "isins": []
    }
  },
  "meta": {
    "requestId": "e5f6a7b8-c9d0-1e2f-3a4b-5c6d7e8f9a0b",
    "durationMs": 312
  }
}
```

> [!NOTE]
>
> Well-known companies like Stripe are answered from curated data in milliseconds. Other sites are read live, which takes 5 to 20 seconds, and the fields can differ a little. Treat every field as optional. See [Caching](/concepts/caching#company-data-curated-first).

## Parameters

`/enrich` takes the same options as [`/brand`](/company-data/brand#color-options). Like `/brand`, its parameters are camelCase. Batches and MCP take the snake\_case spelling (`screenshot_colors`).

| Parameter | Default | Description |
| - | - | - |
| `url` | required | The site to enrich |
| `screenshotColors` | none | Also sample N dominant colors from a screenshot (2–12) |
| `css` | `false` | Also extract colors from stylesheets |
| `html` | `false` | Also extract colors from HTML attributes |
| `javascript` | `false` | Also extract colors from JavaScript |
| `filterAchromatic` | `false` | Drop near-white, near-black and grey colors |
| `designTokens` | `false` | Add `brand.design_tokens`. See [design tokens](/company-data/brand#design-tokens). |
| `screenshotWidth`, `screenshotHeight` | `1440`, `900` | Viewport for the screenshot used for colors and `screenshot_url` (320–3000) |
| `screenshotFormat` | `jpeg` | `jpeg`, `png` or `pdf` |
| `screenshotFullPage` | `false` | Capture the whole scrollable page |
| `disableAdblocker` | `false` | Turn off the built-in ad blocker |

The screenshot settings here only shape the screenshot `/enrich` takes for itself. To capture pages, use [`/screenshot`](/web-data/screenshot), which has its own options and limits.

## For many domains

Send up to 500 domains as one job with [`POST /batch/enrich`](/jobs/batches). Each domain costs the same 12 credits, and you don't have to manage concurrency yourself.

## Next

> [card] [Enrich signups and leads](/recipes/enrich-signups)
>
> A complete recipe: from a work email to a prefilled profile.

> [card] [API reference](/api-reference/endpoint/enrich)
>
> Every parameter, and a playground to try it.


# Logo CDN
Source: https://docs.prefetch.io/company-data/logo-cdn

Any company's logo as an image URL you put straight in an <img> tag. No credits: every plan includes a monthly logo quota.

```html theme={"theme":"css-variables"}
<img src="https://logo.prefetch.io/stripe.com?token=pk_YOUR_TOKEN" alt="Stripe" width="64" height="64" />
```

The logo CDN serves any domain's logo as an image, from Cloudflare's network. Use it wherever you show companies, such as customer lists, transaction feeds, CRM records and search results, without storing a single image yourself.

* **No credits.** Logo requests don't touch your credit balance: each plan includes a monthly quota of them.
* **Embeddable.** The `token` is a *publishable* token: it serves logo images and nothing else, so it is safe in your HTML. It is not your API key.
* **Always an image.** A domain whose logo isn't known yet gets a letter mark in a stable color, and its logo is looked up in the background. The next request usually has it.

## Your token

Get it from the API with your API key:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/logo/token" -H "X-API-Key: $PREFETCH_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "token": "pk_4f1c9e2b7a0d4c3e8b6a1f2d3c4b5a69",
    "cdn_url": "https://logo.prefetch.io",
    "example": "https://logo.prefetch.io/stripe.com?token=pk_4f1c9e2b7a0d4c3e8b6a1f2d3c4b5a69",
    "quota": 100000,
    "used": 1234,
    "period": "2026-10-01"
  }
}
```

There's one token per organization, and it stays the same when you rotate API keys, so logos already on your pages keep working. If someone else is using your token against your quota, [rotate it](/api-reference/endpoint/logo-token-rotate). Every logo embedded with the old token stops loading at once.

## Parameters

```
https://logo.prefetch.io/<domain>?token=<token>[&size=128][&format=png][&theme=light][&greyscale=true][&fallback=monogram]
```

| Parameter | Default | Values |
| - | - | - |
| `<domain>` | required | Any domain: `stripe.com`, `www.stripe.com` and `https://stripe.com/pricing` all mean `stripe.com`. |
| `token` | required | Your publishable token. |
| `size` | `128` | 16–512 pixels. Logos are square, centred on a transparent background. |
| `format` | `png` | `png`, `webp` or `jpeg` (`jpg` works too). |
| `theme` | `light` | The background a JPEG is flattened onto (`light` is white, `dark` near-black). PNG and WebP stay transparent. |
| `greyscale` | `false` | `true` for a grey logo. |
| `fallback` | `monogram` | What a domain without a known logo gets: `monogram` (the letter mark), `404`, or `transparent` (an empty image). |

Unknown values fall back to the default instead of failing, because a broken image helps nobody.

## Examples

```html HTML theme={"theme":"css-variables"}
<img src="https://logo.prefetch.io/linear.app?token=pk_YOUR_TOKEN&size=48" width="24" height="24" alt="Linear" />
```

```jsx React theme={"theme":"css-variables"}
function CompanyLogo({ domain, size = 32 }) {
  return (
    <img
      src={`https://logo.prefetch.io/${domain}?token=${process.env.NEXT_PUBLIC_PREFETCH_LOGO_TOKEN}&size=${size * 2}`}
      width={size}
      height={size}
      alt=""
      loading="lazy"
      style={{ borderRadius: 6 }}
    />
  );
}
```

```markdown Markdown theme={"theme":"css-variables"}
![Stripe](https://logo.prefetch.io/stripe.com?token=pk_YOUR_TOKEN&size=64)
```

Request twice the size you display for sharp logos on high-density screens. The letter mark is a square; round it with CSS if you want a circle.

## Where logos come from

In order: Prefetch's curated brand data; the icons the site declares for itself (its apple touch icon, icons and web app manifest), largest first; and, when those are all tiny, the logo in the page itself. The result is stored once and every size and format is cut from it. Logos are cached at the edge for a week.

## Quotas

| Plan | Logo requests per month |
| - | - |
| Free | 100,000 |
| Starter | 250,000 |
| Pro | 1,000,000 |
| Growth | 3,000,000 |
| Scale | 10,000,000 |
| Enterprise | Unlimited |

Months are calendar months (UTC), and the count resets on the 1st. Only images served count. An invalid token, a quota refusal or a `fallback=404` doesn't count, and browsers cache each logo for a day, so repeat views are free. Past the quota, requests get `429` until the 1st or until you upgrade.

## Errors

| Status | When |
| - | - |
| `400` | The path is not a domain. |
| `401` | No token, or not a valid one (a rotated token, for example). |
| `429` | Your organization's monthly logo quota is used up. |

Errors are JSON with an `error` message. The logo CDN is not available through RapidAPI.

## Next

> [card] [Build a company directory](/recipes/company-directory)
>
> A recipe for a searchable list of companies with logos.

> [card] [Brand](/company-data/brand)
>
> Need colors, fonts and every logo variant? Use `/brand`.


# Resolve a name
Source: https://docs.prefetch.io/company-data/resolve

Turn a company, brand or product name into the domain of its official website. 1 credit, 3 with a live lookup, 0 when nothing matches.

Every other endpoint takes a URL. `/resolve` is how you get one when all you have is a name: `Stripe` → `stripe.com`, `Delta` → `delta.com`, `The Coca-Cola Company` → `coca-cola.com`.

Results are ranked, one per domain, and each has a `confidence` from 0 to 1. Only the first result can reach **0.8**. When it does, that's the answer. Anything lower is a candidate to check.

Case, accents, punctuation and legal suffixes don't matter. "The Coca-Cola Company", "coca-cola" and "Coca Cola" are the same query.

## Where answers come from

* **The name index:** about 550,000 brands, companies, websites, software products and publications, answered in milliseconds. Reviewed brand data always ranks first.
* **A live lookup:** only with `live=true`, and only when the index has no answer at 0.8 or above. Candidate domains are proposed, and each one is checked against its own homepage: the site has to call itself by the name you asked for. Parked and for-sale domains never pass. It takes a few seconds, and the verified answer is added to the index, so the next lookup is instant.

## Example requests

```bash Index only theme={"theme":"css-variables"}
curl "https://api.prefetch.io/resolve?name=Delta" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash With a live lookup theme={"theme":"css-variables"}
curl "https://api.prefetch.io/resolve?name=Linear&live=true" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const params = new URLSearchParams({ name: "Delta", live: "true" });

const res = await fetch(`https://api.prefetch.io/resolve?${params}`, {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

const [best] = data.results;
if (best && best.confidence >= 0.8) {
  console.log(`${data.query} → ${best.domain}`);
} else {
  console.log("No confident answer. Candidates:", data.results.map((r) => r.domain));
}
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/resolve",
    params={"name": "Delta", "live": "true"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
results = r.json()["data"]["results"]
if results and results[0]["confidence"] >= 0.8:
    print(results[0]["domain"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "query": "Delta",
    "results": [
      { "name": "Delta Air Lines", "domain": "delta.com", "url": "https://delta.com", "confidence": 0.92, "source": "index" },
      { "name": "DELTA", "domain": "delta.nl", "url": "https://delta.nl", "confidence": 0.79, "source": "index" },
      { "name": "Delta Holding", "domain": "deltaholding.rs", "url": "https://deltaholding.rs", "confidence": 0.79, "source": "index" }
    ],
    "count": 3,
    "live_used": false,
    "warnings": []
  },
  "meta": {
    "requestId": "b4e3d2c1-8a7b-4c3d-9e2f-1a3b5c7d9e1f",
    "durationMs": 41
  }
}
```

## Reading the response

| Field | Meaning |
| - | - |
| `results[0].confidence` | 0.8 or above: this is the answer. Below: a candidate. Check it, or retry with `live=true`. |
| `source` | `curated` (reviewed brand data), `index` (the name index), or `live` (verified against the site during this request). |
| `domain` | A bare host, ready for the `url` parameter of `/enrich`, `/brand`, `/company` and the rest. |
| `live_used` | Whether the live lookup ran, and so whether you were billed 3 credits. |
| `warnings` | Notes that didn't stop the request. If the live lookup couldn't run, you get the index's answer at the index price, and a warning saying so. |

No match is still a `200`, with an empty `results` list.

## Credits

| Outcome | Credits |
| - | - |
| Answered from the index | 1 |
| Nothing matched, without `live` | 0 |
| `live=true` and the live lookup ran | 3, whether or not it found anything |
| `live=true`, but the index was already confident | 1 |

## Typeahead

`/resolve` also completes partial names. `stri` returns Stripe first, so you can put it behind a search box. Completions always score below 0.8: they're suggestions, not answers. Leave `live` off for typeahead, and debounce keystrokes, because each request counts against your rate limit.

## Next

> [card] [Enrich a company](/company-data/enrich)
>
> Everything about the company behind the domain you found. **12 credits.**

> [card] [API reference](/api-reference/endpoint/resolve)
>
> Every parameter, and a playground to try it.


# Styleguide
Source: https://docs.prefetch.io/company-data/styleguide

A site's design system: colors by role, type scale, spacing, radii, shadows and component styles, plus CSS variables and a Tailwind theme. 10 credits.

`/styleguide` renders a page in a real browser and reads its design system off what's on screen, the way a designer would write it down to rebuild the site's look:

* **Colors by role:** `primary` (the main button's fill), `secondary`, `accent`, `background`, `surface`, `text`, `text_muted`, `heading`, `link` and `border`, plus the full palette.
* **Typography:** the heading, body and monospace faces with their font stacks, and the type scale: `h1` to `h6`, `body`, `small`, `label` and `nav`, each with size, weight, line height, letter spacing and text transform. The ratio between steps is reported, and named when it's a classic one (*major third*, *perfect fourth*).
* **Spacing:** the base unit most margins and paddings are a multiple of, and the scale in use.
* **Radii and shadows:** small, medium and large, and whether the site uses pills.
* **Components:** the primary and secondary button (fill, text, border, radius, weight, font size, height, padding, shadow), the input, the card and the link.
* **Breakpoints:** the widths where the CSS changes layout.
* **CSS variables:** the site's own custom properties for colors, lengths, fonts and shadows.

`exports` has the same guide as **CSS custom properties** and a **Tailwind theme**, ready to paste. Point a coding agent at a site and it can build UI that looks like it.

For logos, the logo's own colors, fonts and social links, use [`/brand`](/company-data/brand).

## Example requests

```bash cURL theme={"theme":"css-variables"}
curl "https://api.prefetch.io/styleguide?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash Dark theme theme={"theme":"css-variables"}
curl "https://api.prefetch.io/styleguide?url=https://github.com&dark_mode=true" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js (write a Tailwind preset) theme={"theme":"css-variables"}
import { writeFile } from "node:fs/promises";

const res = await fetch("https://api.prefetch.io/styleguide?url=https://linear.app", {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

await writeFile("brand.css", data.exports.css);
await writeFile("tailwind.brand.js", `export default ${JSON.stringify(data.exports.tailwind, null, 2)};\n`);
```

```python Python theme={"theme":"css-variables"}
import json, os, requests

r = requests.get(
    "https://api.prefetch.io/styleguide",
    params={"url": "https://linear.app"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
data = r.json()["data"]

with open("brand.css", "w") as f:
    f.write(data["exports"]["css"])
with open("tailwind.brand.json", "w") as f:
    json.dump(data["exports"]["tailwind"], f, indent=2)
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "url": "https://stripe.com",
    "domain": "stripe.com",
    "dark_mode": false,
    "styleguide": {
      "color_scheme": "light",
      "colors": {
        "primary": "#533AFD", "secondary": null, "accent": null,
        "background": "#FFFFFF", "surface": "#E5EDF5",
        "text": "#50617A", "text_muted": "#64748D", "heading": "#061B31",
        "link": "#533AFD", "border": "#E5EDF5"
      },
      "palette": [{ "hex": "#533AFD", "role": "primary" }, { "hex": "#FFFFFF", "role": "background" }],
      "typography": {
        "font_families": {
          "heading": { "family": "sohne-var", "stack": ["sohne-var", "SF Pro Display", "sans-serif"] },
          "body": { "family": "sohne-var", "stack": ["sohne-var", "SF Pro Display", "sans-serif"] },
          "mono": null
        },
        "styles": {
          "h1": { "font_family": "sohne-var", "font_size": "48px", "font_weight": 300, "line_height": "55.2px", "letter_spacing": "-0.96px", "text_transform": null },
          "body": { "font_family": "sohne-var", "font_size": "16px", "font_weight": 300, "line_height": "22.4px", "letter_spacing": null, "text_transform": null }
        },
        "base_font_size": "16px",
        "scale": { "ratio": 1.441, "name": "augmented fourth" },
        "web_fonts": { "google_fonts": [], "adobe_fonts": [] }
      },
      "spacing": { "base_unit": "4px", "scale": ["4px", "8px", "12px", "16px", "24px", "32px", "40px", "64px"] },
      "radius": { "small": "4px", "medium": "6px", "large": "16px", "full": true, "scale": ["4px", "6px", "16px", "9999px"], "button": "4px", "input": "4px", "card": "6px" },
      "shadows": {
        "small": "rgba(23, 23, 23, 0.06) 0px 3px 6px 0px",
        "medium": null,
        "large": "rgba(23, 23, 23, 0.08) 0px 15px 35px 0px",
        "scale": ["rgba(23, 23, 23, 0.06) 0px 3px 6px 0px", "rgba(23, 23, 23, 0.08) 0px 15px 35px 0px"]
      },
      "borders": { "width": "1px", "color": "#E5EDF5" },
      "components": {
        "button_primary": { "background": "#533AFD", "text_color": "#FFFFFF", "border_color": null, "border_radius": "4px", "font_weight": 400, "font_family": "sohne-var", "font_size": "16px", "height": "48px", "padding": "15.5px 24px 16.5px", "text_transform": null, "letter_spacing": null, "box_shadow": null },
        "button_secondary": null,
        "input": null,
        "card": { "background": "#FFFFFF", "border_color": null, "border_width": null, "border_radius": "6px", "box_shadow": "rgba(50, 50, 93, 0.12) 0px 16px 32px 0px", "padding": null },
        "link": { "color": "#533AFD", "text_decoration": "none", "font_weight": 400 }
      },
      "breakpoints": ["640px", "768px", "1024px"],
      "css_variables": { "--hds-color-accent-border-solid": "#533afd" }
    },
    "exports": {
      "css": ":root {\n  --color-primary: #533AFD;\n  --color-background: #FFFFFF;\n  …\n}\n",
      "tailwind": { "theme": { "extend": { "colors": { "primary": "#533AFD", "background": "#FFFFFF" }, "fontSize": { "h1": ["48px", { "lineHeight": "55.2px", "fontWeight": "300", "letterSpacing": "-0.96px" }] } } } }
    }
  },
  "meta": { "requestId": "3c2b1a0f-9e8d-4c7b-8a6f-5e4d3c2b1a0f", "durationMs": 4532 }
}
```

## How it reads a site

Everything comes from computed styles in the rendered page, so it reflects what visitors see, whatever CSS framework the site uses:

* Colors are read in any CSS color space (`oklch()`, `lab()` and `color()` included) and returned as hex. Translucent colors are blended over what's behind them.
* A text style is the one most instances of an element share, weighted by text, so one oversized hero heading doesn't speak for every heading.
* Spacing, radii and shadows are counted across up to 2,500 visible elements. One-off values don't make the scale, Tailwind's transparent placeholder shadows are dropped, and hairline "ring" shadows count as borders, not elevation.
* `css_variables` lists the custom properties in scope on the page, with names that look like design tokens first.

It's best effort: a value the page gives no reliable answer for is `null`. Set `dark_mode=true` to read a site's dark theme, and `color_scheme` tells you which theme you got.

## Credits

**10 credits** per request. Styleguides are always read live, never from curated data. A repeat request can be answered from the request cache.

## Next

> [card] [Build on-brand UI](/recipes/on-brand-ui)
>
> A recipe for turning a styleguide into a Tailwind theme with a coding agent.

> [card] [API reference](/api-reference/endpoint/styleguide)
>
> Every parameter, and a playground to try it.


# Card transactions
Source: https://docs.prefetch.io/company-data/transaction

Turn a card transaction descriptor into the merchant behind it: name, website, logo, processor and location. 3 credits, 1 for a line seen in the last week.

Bank statement lines are written for card networks, not people: `SQ *BLUE BOTTLE COFFE OAKLAND CA`, `PAYPAL *SPOTIFYAB`, `AMZN Mktp US*2K4LX9B12`. `/transaction` reads one and tells you who was paid:

| Descriptor | Merchant | Website | Processor | Where |
| - | - | - | - | - |
| `SQ *BLUE BOTTLE COFFE OAKLAND CA` | Blue Bottle Coffee | bluebottlecoffee.com | Square | Oakland, CA |
| `PAYPAL *SPOTIFYAB` | Spotify | spotify.com | PayPal | |
| `AMZN Mktp US*2K4LX9B12` | Amazon | amazon.com | | |
| `CHECKCARD 0412 STARBUCKS STORE 12345 SEATTLE WA` | Starbucks | starbucks.com | | Seattle, WA |
| `VENMO *JOHN SMITH` | A payment to a **person** | | Venmo | |
| `MONTHLY MAINTENANCE FEE` | A bank **fee** | | | |

Cut-off words are completed (card networks truncate descriptors at 22 characters), and processor prefixes and store numbers are dropped. Lines that aren't purchases say so in `kind`: `person`, `transfer`, `fee`, `atm` or `refund`.

The merchant's name is then resolved to its website the way [`/resolve`](/company-data/resolve) does it: the name index first, then a live lookup that checks each candidate against its homepage, using the line's city to tell local businesses apart.

`logo_url` points at the merchant's logo on the [logo CDN](/company-data/logo-cdn), with your publishable token, ready for an `<img>` tag. `include_brand=true` adds the merchant's full brand (logos, colors, fonts) as [`/brand`](/company-data/brand) returns it.

## Example requests

```bash cURL theme={"theme":"css-variables"}
curl -G "https://api.prefetch.io/transaction" \
  --data-urlencode "descriptor=SQ *BLUE BOTTLE COFFE OAKLAND CA" \
  --data-urlencode "country=US" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash POST, with the brand theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/transaction" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "descriptor": "PAYPAL *SPOTIFYAB", "mcc": "5815", "include_brand": true }'
```

```javascript Node.js theme={"theme":"css-variables"}
const lines = ["SQ *BLUE BOTTLE COFFE OAKLAND CA", "NETFLIX.COM 866-579-7172 CA", "VENMO *JOHN SMITH"];

for (const descriptor of lines) {
  const res = await fetch("https://api.prefetch.io/transaction", {
    method: "POST",
    headers: { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ descriptor, country: "US" }),
  });
  const { data } = await res.json();
  const who = data.kind === "merchant" ? `${data.merchant.name} (${data.merchant.domain ?? "no website"})` : data.kind;
  console.log(descriptor, "→", who);
}
```

```python Python theme={"theme":"css-variables"}
import os, requests

lines = ["SQ *BLUE BOTTLE COFFE OAKLAND CA", "NETFLIX.COM 866-579-7172 CA", "VENMO *JOHN SMITH"]

for descriptor in lines:
    r = requests.post(
        "https://api.prefetch.io/transaction",
        headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
        json={"descriptor": descriptor, "country": "US"},
    )
    data = r.json()["data"]
    who = data["merchant"]["name"] if data["kind"] == "merchant" else data["kind"]
    print(descriptor, "→", who)
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "descriptor": "SQ *BLUE BOTTLE COFFE OAKLAND CA",
    "kind": "merchant",
    "merchant": {
      "name": "Blue Bottle Coffee",
      "domain": "bluebottlecoffee.com",
      "url": "https://bluebottlecoffee.com",
      "confidence": 0.88,
      "source": "live"
    },
    "candidates": [
      { "name": "Blue Bottle Coffee", "domain": "bluebottlecoffee.com", "url": "https://bluebottlecoffee.com", "confidence": 0.88, "source": "live" }
    ],
    "payment_processor": "Square",
    "location": { "city": "Oakland", "region": "CA", "country": "US" },
    "category": "Coffee shop",
    "logo_url": "https://logo.prefetch.io/bluebottlecoffee.com?token=pk_4f1c9e2b7a0d4c3e8b6a1f2d3c4b5a69",
    "parsed_by": "model",
    "warnings": []
  },
  "meta": { "requestId": "8a7b6c5d-4e3f-4a2b-9c1d-0e9f8a7b6c5d", "durationMs": 1577 }
}
```

## Reading the response

| Field | Meaning |
| - | - |
| `kind` | `merchant`, or what else the line is. Only a `merchant` has a `merchant` object. |
| `merchant.name` | The trading name, even when no website was found. Many local businesses have none. |
| `merchant.domain` | The website, when one was found with a confidence of at least 0.6. At 0.8 or above, treat it as the answer. Below 0.6 it appears only in `candidates`. |
| `candidates` | Every domain considered, best first, including low-confidence ones. |
| `logo_url` | `null` when no website was found, or for keys without a logo token (RapidAPI). |
| `parsed_by` | `rules` when the language model was unavailable and the line was read by pattern alone. That reading is less reliable, and `warnings` says so. |

`country` (where the card was used) and `mcc` (the merchant category code from your card data) are optional hints that help with ambiguous lines.

## Credits

| Outcome | Credits |
| - | - |
| A line read and resolved | 3 |
| The same line, country and MCC looked up in the last 7 days | 1 |
| `include_brand=true`, and a brand was returned | +10 |
| Failures | 0 |

Statements repeat the same merchants every month, so after the first month most lines cost 1 credit.

> [!NOTE]
>
> Lines whose merchant is already in the name index answer in about a second. Others run a live lookup, which usually takes 2 to 5 seconds.

## Next

> [card] [Build a merchant feed](/recipes/merchant-feed)
>
> A recipe for readable transaction rows with logos.

> [card] [API reference](/api-reference/endpoint/transaction)
>
> Every parameter, and a playground to try it.


# Prefetch vs Brandfetch
Source: https://docs.prefetch.io/compare/brandfetch

How Prefetch and Brandfetch compare for logos, brand data, merchant lookups and name search, and what Prefetch adds with web data.

Brandfetch specializes in brand data: logos in every variant, brand profiles, brand search and transaction lookups. Prefetch covers the same core jobs for domains, and adds web data: scraping, search, crawling and monitors, with one key and one credit balance.

> [!NOTE]
>
> Compared with [Brandfetch's public documentation](https://docs.brandfetch.com) as of November 2026.

## At a glance

| | Prefetch | Brandfetch |
| - | - | - |
| Embeddable logo URLs | [Logo CDN](/company-data/logo-cdn) | Logo API |
| Free logo requests | 100,000 a month on Free, up to 10,000,000 on Scale | 1,000,000 a month, fair use |
| Logo lookups by | Domain | Domain, stock or ETF ticker, ISIN, crypto symbol |
| Logo variants | One square logo per domain | Icon, symbol and logo, each in light and dark |
| Logo sizes and formats | 16 to 512 pixels; PNG, WebP, JPEG; greyscale | 16 to 2048 pixels; WebP, PNG, JPEG, and SVG for logos and symbols |
| Missing logos | Letter mark, transparent or `404` | Letter mark, Brandfetch mark, transparent or `404` |
| Brand profile | [`/brand`](/company-data/brand), [`/enrich`](/company-data/enrich) | Brand API |
| Company details and industry | [`/company`](/company-data/company), IAB [`/classify`](/company-data/classify) | Firmographics in the Brand API |
| Design system with CSS and Tailwind exports | [`/styleguide`](/company-data/styleguide) | No |
| Narrative brand context for LLMs: positioning, voice, competitors | No. [`/classify`](/company-data/classify) returns descriptions and a tagline. | Brand Context API |
| Name → domain | [`/resolve`](/company-data/resolve) | Brand Search API |
| Card transaction → merchant | [`/transaction`](/company-data/transaction) | Transaction API |
| Scrape, crawl, search, answers, monitors | Yes | No |
| Brand batches | [`/batch/brand`](/jobs/batches), [`/batch/enrich`](/jobs/batches), up to 500 domains | Brand API batch |
| GraphQL | No | Yes |
| Excel, PowerPoint, Google Sheets, Airtable add-ons | No. [Clay, n8n, Zapier and Make guides](/integrations/overview). | Yes |
| Pay per request without an account | No | Yes, for agents |
| MCP | Yes, with OAuth sign-in | Yes |
| Compliance | Not covered in the docs. Ask [hi@prefetch.io](mailto:hi@prefetch.io). | SOC 2 Type 2, zero data retention |

## How access works

* **Logos:** both use a publishable ID in the URL: `token` on Prefetch, `c` on Brandfetch. Brandfetch requires logo URLs to be embedded in pages, and doesn't permit fetching them from scripts. For logo files on your server, Prefetch's [`/brand`](/company-data/brand) returns logo URLs you can download.
* **Brand data:** Brandfetch's Brand API includes 100 free requests, then a paid plan. Prefetch's `/brand` costs 10 credits, and the Free plan includes 1,000 credits a month.

## When Brandfetch is the better fit

* You show logos for stocks, ETFs or crypto, by ticker, ISIN or symbol.
* You need wordmarks and symbols as well as icons, light and dark variants, or SVG from the CDN.
* You serve more logo requests than Prefetch's plan quotas.
* You work in Excel, PowerPoint, Google Sheets or Airtable, or prefer GraphQL.

## When Prefetch is the better fit

* You need brand data **and** web data, such as scraping a site you just enriched or monitoring a customer's pricing page.
* You want a site's full design system as CSS variables and a Tailwind theme.
* You want IAB industry categories and company details from a domain.

> [card] [Migrate from Clearbit or Brandfetch logos](/migrate/logos)
>
> Logo URL parameters, plus the Brand, Search and Transaction APIs.


# Prefetch vs Context.dev
Source: https://docs.prefetch.io/compare/context-dev

How Prefetch and Context.dev compare: two APIs that both combine web data with brand and company data.

Context.dev is the closest product to Prefetch. Both offer scraping, map, crawl, search, sourced answers, brand profiles, styleguides, an embeddable logo URL, batches and monitors behind one key. They differ in depth: Context.dev adds browser actions, document parsing, people, company and news search, and official SDKs. Prefetch adds a dedicated company endpoint, the IAB industry taxonomy, screenshots, monitor email alerts and cron schedules.

> [!NOTE]
>
> Compared with [Context.dev's public documentation](https://docs.context.dev) as of November 2026.

## At a glance

| | Prefetch | Context.dev |
| - | - | - |
| Scrape to markdown, HTML, images, JSON, screenshot | Yes, plus `summary`, `raw_html` and `links` | Yes, plus `product`, `highlights`, `parse` and `bytes` |
| Prebuilt parsers for Google Maps, App Store, Instagram, TikTok, Reddit, G2, Yelp | No | Yes |
| Browser actions and profiles | No | Yes |
| Map, crawl, search | Yes | Yes |
| Crawl | An async job, up to 500 pages | One request, up to 500 pages, or a batch for larger sites |
| Sourced answers | `/answers`, `fast` or `ultra` | `/web/answers`, `fast` or `ultra` |
| Document parsing and OCR | PDFs served from a URL | Parse, with OCR |
| Brand profile | [`/brand`](/company-data/brand), [`/enrich`](/company-data/enrich) | Brand, by domain, name, email, ticker, transaction or URL |
| Company details | [`/company`](/company-data/company): legal name, emails, addresses, key pages | Inside the brand profile |
| Industry | IAB category and subcategory, from [`/classify`](/company-data/classify) | EIC industry and subindustry, in the brand profile |
| Styleguide | Yes, with CSS and Tailwind exports | Yes |
| Screenshots | [`/screenshot`](/web-data/screenshot), with 10 device presets | A scrape format |
| Embeddable logos | [Logo CDN](/company-data/logo-cdn), with size, format and greyscale | Logo Link, with icon or wordmark |
| People, company and news search | No | Yes |
| Batches | Scrape or 6 endpoints, up to 500 URLs, charged as results complete | Scrape or crawl, up to 100,000 URLs, credits reserved up front |
| Monitors | Scrape, crawl and search targets; goals; JSON field tracking | Page, sitemap, extract and search targets; semantic judging |
| Monitor alerts | Webhook and email | Webhook, with delivery history and replay |
| Monitor schedules | Phrases or cron in any timezone, down to every minute on Scale | Fixed intervals, from every 10 minutes |
| SDKs | None. REST and [OpenAPI](/api-reference/openapi.json). | TypeScript, Python, Ruby, Go, PHP, plus a CLI and an agent skill |
| MCP | Yes, with OAuth sign-in | Yes |
| Zero data retention, access policies | No | Yes |
| Compliance | Not covered in the docs. Ask [hi@prefetch.io](mailto:hi@prefetch.io). | SOC 2 Type II |

## Credits for the same work

Many prices match. A credit isn't the same price on each, so compare plans as well.

| Work | Prefetch | Context.dev |
| - | - | - |
| Scrape a page | 1 | 1 |
| JSON extraction from a page | +3 | +4 |
| Map a site | 1 | 1, or 2 with `search` |
| Crawl | 1 per page | 1 per successful page |
| Search | 2 per 10 results | 1 per 10 results, +1 per result with markdown |
| Answers | 10 `fast`, 100 `ultra` | 10 `fast`, 100 `ultra` |
| Brand profile | 10 (`/brand`), or 12 with company and industry (`/enrich`) | 10 |
| Styleguide | 10 | 10 |
| Free plan | 1,000 credits a month | 1,000 credits a month |

## Defaults that differ

* **Caching:** Context.dev accepts scrapes cached up to 3 days by default. Prefetch fetches live unless you set `max_age`.
* **Crawl regexes:** Context.dev matches the full URL, while Prefetch matches the path and query.
* **Out of credits:** Context.dev returns `402`. Prefetch returns `403` with `CREDITS_EXHAUSTED`.

## When Context.dev is the better fit

* You need browser actions, logged-in profiles or social-platform parsers.
* You need people, company or news search, or document OCR.
* You batch more than 500 URLs in one job.
* You want an official SDK, zero data retention, or a SOC 2 report today.

## When Prefetch is the better fit

* You need IAB industry categories, or company details as their own call.
* You want monitor alerts by email, or schedules in cron with a timezone and gaps under 10 minutes.
* You want screenshots with device presets as a first-class endpoint.
* You want batches charged only for results that come back.

> [card] [Migrate from Context.dev](/migrate/context-dev)
>
> Endpoint and parameter mapping, and the behaviors that change.


# Prefetch vs Firecrawl
Source: https://docs.prefetch.io/compare/firecrawl

How Prefetch and Firecrawl compare for scraping, crawling, search and monitoring, and what Prefetch adds with company data.

Firecrawl and Prefetch overlap on web data: scrape, map, crawl, batch scrape, search and monitors work much the same way, down to the endpoint names. The difference is scope. Firecrawl goes deeper on the web, with browser interaction, an agent and document parsing. Prefetch adds company data: brand, company details, industry, merchants and logos.

> [!NOTE]
>
> Compared with [Firecrawl's public documentation](https://docs.firecrawl.dev) as of November 2026.

## At a glance

| | Prefetch | Firecrawl |
| - | - | - |
| Scrape to markdown, HTML, links, images, JSON, screenshot | Yes | Yes |
| Summaries | `summary` format | `summary` format |
| Map, crawl, batch scrape | Yes | Yes |
| Web search with page content | Yes | Yes, plus research, developer and government indexes |
| Monitors with goals and judging | Yes, with webhook and email alerts | Yes, with webhook, email and Slack alerts |
| Researched answers in your JSON shape | [`/answers`](/web-data/answers) | Agent |
| Click, type and navigate before scraping | No | Actions, Interact and Browser Sandbox |
| Parse local files (PDF, DOCX, XLSX…) | No. PDFs served from a URL are read. | Parse |
| PII redaction | No | Yes |
| Prompt-injection check | Yes | Yes |
| Brand identity | [`/brand`](/company-data/brand) and [`/styleguide`](/company-data/styleguide) | `branding` scrape format |
| Company details, IAB industry, enrichment | [`/company`](/company-data/company), [`/classify`](/company-data/classify), [`/enrich`](/company-data/enrich) | No |
| Name → domain, transaction → merchant | [`/resolve`](/company-data/resolve), [`/transaction`](/company-data/transaction) | No |
| Embeddable logo CDN | [Yes](/company-data/logo-cdn) | No |
| SDKs | None. REST and [OpenAPI](/api-reference/openapi.json). | Python, Node, Go, Java, Ruby, Rust, .NET, PHP, Elixir, plus a CLI |
| MCP | Yes, with OAuth sign-in | Yes, including a keyless mode |
| Open source and self-hosting | No | Yes |
| Compliance | Not covered in the docs. Ask [hi@prefetch.io](mailto:hi@prefetch.io). | SOC 2 Type II, zero data retention, SSO |

## Credits for the same work

Both price web data in credits, and many costs line up. A credit isn't the same price on each, so compare plans as well.

| Work | Prefetch | Firecrawl |
| - | - | - |
| Scrape a page | 1 | 1 |
| JSON extraction from a page | +3 | +4 |
| Prompt-injection check | +3 | +4 |
| Map a site | 1 | 1 |
| Crawl | 1 per page | 1 per page |
| Search | 2 per 10 results | 2 per 10 results |
| Free plan | 1,000 credits a month | 1,000 credits a month |

Prefetch never charges a failed request, and charges crawls and batches only for pages returned. See [Credits](/concepts/credits).

## Defaults that differ

* **Caching:** Firecrawl serves pages cached up to 2 days by default. Prefetch fetches live unless you set `max_age`.
* **Parameters:** Firecrawl uses camelCase, and Prefetch uses snake\_case.
* **Errors:** Prefetch errors carry `error_code` and `retryable`, so code can decide whether to retry.

## When Firecrawl is the better fit

* You need to click, fill forms or log in before you read a page.
* You need to parse local documents, or redact personal data.
* You want an official SDK in your language, or to self-host.
* You need a SOC 2 report today.

## When Prefetch is the better fit

* You need web data **and** company data, without a second vendor or a second balance.
* You show companies in your product and want logos, colors, industry and merchant names.
* You want monitor alerts by email as well as webhook.

> [card] [Migrate from Firecrawl](/migrate/firecrawl)
>
> Endpoint and parameter mapping, response differences and webhook signatures.


# Compare Prefetch
Source: https://docs.prefetch.io/compare/overview

How Prefetch compares with Firecrawl, Context.dev and Brandfetch: what each covers, where each is the better fit, and how to switch.

Prefetch covers two jobs that usually take two vendors: **company data** (brand, logos, company details, industry, merchants) and **web data** (scraping, search, crawling and monitoring), with one API key and one credit balance.

> [!NOTE]
>
> These pages compare Prefetch with each product's public documentation as of November 2026. Products change, so check their docs before you decide. Spotted something out of date? Email [hi@prefetch.io](mailto:hi@prefetch.io).

## At a glance

| | Prefetch | Firecrawl | Context.dev | Brandfetch |
| - | - | - | - | - |
| Scrape, map, crawl, search | Yes | Yes | Yes | No |
| Batch jobs | Up to 500 URLs | Yes | Up to 100,000 URLs | Brand lookups |
| Researched answers | Yes | Agent | Yes | No |
| Monitors with change judging | Yes | Yes | Yes | No |
| Brand assets (logos, colors, fonts) | Yes | `branding` scrape format | Yes | Yes |
| Company details and industry | Yes, IAB | No | Yes, EIC | Firmographics |
| Name → domain | Yes | No | Yes | Yes |
| Card transaction → merchant | Yes | No | Yes | Yes |
| Embeddable logo CDN | Yes | No | Yes | Yes |
| Browser actions | No | Yes | Yes | No |
| Document parsing | PDFs from a URL | Yes | Yes | No |
| People and news data | No | No | Yes | No |
| Official SDKs | No | 9 languages, plus a CLI | 5 languages, plus a CLI | No |
| MCP server | Yes | Yes | Yes | Yes |
| Self-hosting | No | Yes, open source | No | No |

## Compare in detail

> [card] [Prefetch vs Firecrawl](/compare/firecrawl)
>
> Web scraping and crawling, with or without company data.

> [card] [Prefetch vs Context.dev](/compare/context-dev)
>
> The closest match: web data and brand data in one API.

> [card] [Prefetch vs Brandfetch](/compare/brandfetch)
>
> Logos and brand data, with or without web data.

## Switching

> [card] [From Firecrawl](/migrate/firecrawl)
>
> Endpoint and parameter mapping.

> [card] [From Context.dev](/migrate/context-dev)
>
> Endpoint and parameter mapping.

> [card] [From Clearbit or Brandfetch logos](/migrate/logos)
>
> Logo URLs, Brand API and Transaction API.


# Async jobs
Source: https://docs.prefetch.io/concepts/async-jobs

How crawls, batches and monitor checks run in the background: submit, poll, page through results, and read them before they expire.

Most Prefetch endpoints answer in one round trip. Four kinds of work take longer, so they run as background jobs:

| Job | Start it with | Read it with |
| - | - | - |
| [Crawl](/web-data/crawl) | `POST /crawl` | `GET /crawl/{id}` |
| [Batch scrape](/jobs/batches) | `POST /batch/scrape` | `GET /batch/scrape/{id}` |
| [Batch of another endpoint](/jobs/batches) | `POST /batch/{endpoint}` | `GET /batch/{endpoint}/{id}` |
| [Monitor check](/monitors/overview) | A schedule, or `POST /monitor/{id}/run` | `GET /monitor/{id}/checks/{checkId}` |

## The flow

**1. Submit**

The request returns `202 Accepted` with a job id straight away. Crawl and batch ids start with `crw_`. Monitor check ids start with `chk_`.

**2. Wait**

Poll the read endpoint every few seconds, or pass a [`webhook`](/concepts/webhooks) and have results pushed to you.

**3. Read**

Each response holds progress plus one page of results. Follow `next` until it's `null`.

## Statuses

| Status | Meaning |
| - | - |
| `pending` | Queued, not started. A monitor check says `queued`. |
| `running` | In progress. Results finished so far are already readable. |
| `completed` | Finished. |
| `failed` | Stopped on an error. `error` says why. Results stored before it stopped stay readable. |
| `cancelled` | You stopped it with `DELETE`. |

Keep polling while the status is `pending`, `queued` or `running`.

> [!NOTE]
>
> `total` is the number of pages known **so far**. A crawl finds pages as it goes, so `total` rises until the crawl runs out of links or reaches `limit`. Check `status` to know when a job is done, not `completed === total`.

## Pagination

Results come a page at a time, in the order they finished. Each response carries `next`, a path to the following page, such as `/crawl/crw_9f2c…?skip=25&limit=25`. You can also set `skip` and `limit` yourself.

```javascript Node.js theme={"theme":"css-variables"}
const base = "https://api.prefetch.io";
const headers = { "X-API-Key": process.env.PREFETCH_API_KEY };

// Wait for the job to finish
let job;
do {
  await new Promise((r) => setTimeout(r, 5000));
  ({ data: job } = await (await fetch(`${base}/crawl/${id}`, { headers })).json());
} while (job.status === "pending" || job.status === "running");

// Then read every page of results
const results = [...job.data];
for (let next = job.next; next; ) {
  const { data } = await (await fetch(base + next, { headers })).json();
  results.push(...data.data);
  next = data.next;
}
```

```python Python theme={"theme":"css-variables"}
import os, time, requests

base = "https://api.prefetch.io"
headers = {"X-API-Key": os.environ["PREFETCH_API_KEY"]}

while True:
    job = requests.get(f"{base}/crawl/{job_id}", headers=headers).json()["data"]
    if job["status"] not in ("pending", "running"):
        break
    time.sleep(5)

results, nxt = list(job["data"]), job["next"]
while nxt:
    page = requests.get(base + nxt, headers=headers).json()["data"]
    results.extend(page["data"])
    nxt = page["next"]
```

The same loop works for batches: swap the path for `/batch/scrape/{id}` or `/batch/enrich/{id}`.

## Expiry

Crawl and batch results stay readable until the job's `expires_at`, 24 hours after the job was created. Copy what you need before then. Monitor checks are kept for the monitor's `retention_days`.

## Failed and skipped items

One failed page never fails the whole job. Each result carries `ok`, and a failed one carries an [`error_code`](/concepts/errors#error-codes). The `/errors` endpoints list failures and, for crawls, every URL that was skipped and why:

* [`GET /crawl/{id}/errors`](/api-reference/endpoint/crawl-errors)
* [`GET /batch/scrape/{id}/errors`](/api-reference/endpoint/batch-scrape-errors)
* [`GET /batch/{endpoint}/{id}/errors`](/api-reference/endpoint/batch-errors)

## Billing

Submitting is free. Results are charged as they complete: when you poll, or when the job ends, whichever comes first, and never twice. Polling often costs nothing extra. Failed items are free. See [Credits](/concepts/credits#crawls-and-batches).

## Over MCP

The MCP tools submit a job and wait for it, up to `wait_seconds` (60 by default). If it finishes in time, you get the results straight away. If not, you get the id to pass to `prefetch_check_crawl_status`. See [How crawling works](/mcp/overview#how-crawling-works).


# Authentication
Source: https://docs.prefetch.io/concepts/authentication

How to authenticate Prefetch API requests: API keys for your own code, OAuth sign-in for apps like Claude and ChatGPT.

## API keys

Every endpoint except `/health` and `/ready` needs an API key. Send it in the `X-API-Key` header:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/classify?url=https://example.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

Create a key on the [dashboard](https://prefetch.io/dashboard).

> [!WARNING]
>
> Never put your API key in browser code. Call Prefetch from your own backend instead. To show logos in a browser, use the [logo CDN](/company-data/logo-cdn), whose token is safe to publish.

## Bearer tokens

`POST /mcp` also accepts your key as a bearer token, because many MCP clients only offer an `Authorization` field:

```bash theme={"theme":"css-variables"}
curl -X POST https://api.prefetch.io/mcp \
  -H "Authorization: Bearer $PREFETCH_API_KEY"
```

If you send both, `X-API-Key` wins. This applies to `/mcp` only: REST endpoints need `X-API-Key`. See [MCP server](/mcp/overview) for client setup.

## OAuth for apps

Apps that can't hold an API key, such as Claude, ChatGPT and Claude Desktop, sign you in instead. You approve the app on prefetch.io, and it gets an access token that it sends as a bearer token:

```bash theme={"theme":"css-variables"}
curl -X POST https://api.prefetch.io/mcp \
  -H "Authorization: Bearer <access token>"
```

You never handle the token yourself. The app gets it, refreshes it and stores it. Its calls bill the newest active API key on your account (the one on your dashboard) and go through the same checks as a key. Access tokens work on the REST endpoints too.

A request with no credentials gets a `401` whose `WWW-Authenticate` header points at `/.well-known/oauth-protected-resource` (or `/.well-known/oauth-protected-resource/mcp` for the MCP server). That's how an app finds where to sign you in.

To remove an app's access, select **Disconnect** under **Connected Apps** on the [dashboard](https://prefetch.io/dashboard). Its next call fails, even if its token hasn't expired.

## How keys are checked

Every request checks your key in this order:

1. **Present:** the key is in the header.
2. **Not revoked:** nobody revoked it.
3. **Not expired:** it hasn't passed its expiry date.
4. **Within its credit limit:** it hasn't used its [credits](/concepts/credits#credit-limits-per-key).

A missing key, or an expired or disconnected access token, returns `401`. Every other failure returns `403`.

| Status | `error_code` | `error` | Cause |
| - | - | - | - |
| `401` | `UNAUTHORIZED` | `"API key required"` | No `X-API-Key` header or access token |
| `401` | `UNAUTHORIZED` | `"The access token has expired"` | A connected app's token expired. The app refreshes it. |
| `401` | `UNAUTHORIZED` | `"This connection to Prefetch was disconnected. Reconnect to continue."` | The app was disconnected on the dashboard |
| `403` | `UNAUTHORIZED` | `"Invalid API key"` | The key doesn't exist |
| `403` | `UNAUTHORIZED` | `"API key has been revoked"` | The key was revoked |
| `403` | `UNAUTHORIZED` | `"API key has expired"` | The key passed its expiry date |
| `403` | `CREDITS_EXHAUSTED` | `"Credit limit exceeded"` | The key used all its credits |

## Keeping keys safe

* Use separate keys for development and production.
* Set a credit limit on each key so a bug can't spend your whole balance.
* Rotate keys regularly on the dashboard.
* Revoke a leaked key straight away.

See the [production checklist](/concepts/production-checklist) before you launch.


# Caching and freshness
Source: https://docs.prefetch.io/concepts/caching

When Prefetch fetches a page live, when it answers from stored or curated data, and how to control it.

Prefetch answers some requests from data it already has. That's faster, and you choose how fresh is fresh enough.

## Pages: live by default

`/scrape`, `/search` (for scraped results), crawls and batch scrapes fetch every page live unless you say otherwise.

Set `max_age` in milliseconds, up to 30 days, to accept a stored copy fetched at most that long ago:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/scrape?url=https://stripe.com/pricing&max_age=3600000" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

* A stored copy answers any mix of formats and comes back faster. It costs the same as a live fetch.
* `metadata.cache_state` says what happened: `hit` or `miss`. A hit carries `metadata.cached_at`.
* Requests that send `headers` are never stored or served from storage.

MCP and REST share the same request cache, so a page fetched over one can be answered from cache over the other.

## Company data: curated first

`/enrich`, `/brand`, `/company`, `/classify` and batches of them answer well-known companies from curated data, in milliseconds. Other sites are read live, which takes 5 to 20 seconds.

Curated answers can carry fewer fields than a live read. Two kinds of request are always read live:

* `/brand` or `/enrich` with `designTokens=true`
* `/styleguide`, although a repeat request can come from the request cache

## Lookups that remember

| Endpoint | What's reused |
| - | - |
| [`/resolve`](/company-data/resolve) | A name verified by a live lookup is added to the index, so the next lookup of that name is instant. |
| [`/transaction`](/company-data/transaction) | The same line, country and MCC looked up in the last 7 days costs 1 credit instead of 3. |
| [Logo CDN](/company-data/logo-cdn) | Logos are cached at the edge for a week, and in browsers for a day. Repeat views don't count against your quota. |

## Caching on your side

Most brand and company data changes rarely. Store it for days, and refresh it on a schedule or when a user asks. For pages that change, a [monitor](/monitors/overview) tells you when to fetch again, instead of re-fetching on a timer.


# Credits
Source: https://docs.prefetch.io/concepts/credits

What each Prefetch endpoint costs, when you're charged, and how plans, refills and top-ups work.

Every request that succeeds costs a fixed number of credits. Fetching one page costs 1, and the endpoints that do more work cost more.

## Credit costs

| Endpoint | Credits |
| - | - |
| `GET /resolve` | 1. 3 when a live lookup runs (`live=true`). 0 when nothing matches. |
| `GET /transaction` | 3. 1 for a line looked up in the last 7 days. +10 with `include_brand`. |
| `GET /enrich` | 12 |
| `GET /brand` | 10 |
| `GET /styleguide` | 10 |
| `GET /company` | 5 |
| `GET /classify` | 5 |
| `GET /scrape` | 1. +3 when you ask for `summary`, `json` or `check_prompt_injection`. |
| `GET /search` | 2 per 10 results, rounded up. Each result page scraped costs what `/scrape` costs. |
| `GET /map` | 1 |
| `GET /screenshot` | 1 |
| `POST /answers` | 10 in `fast` mode. 100 in `ultra` mode, the REST default. |
| `POST /crawl` | Free to submit. 1 per page returned, or 4 with `summary`, `json` or `check_prompt_injection`. |
| `POST /batch/scrape` | Free to submit. 1 per page returned, or 4 with `summary`, `json` or `check_prompt_injection`. |
| `POST /batch/{endpoint}` | Free to submit. Each URL answered costs what one call of that endpoint costs. |
| Monitor checks | 1 per page fetched, +3 when a `json` extraction runs, +1 per page judged against a goal. A search target costs 2 per search, +1 per new result read. |
| Logo CDN images | No credits. Each plan includes a monthly logo quota. |
| Everything else | Free: job status, errors and cancel calls, managing monitors, `/logo/token`, `/health` and `/ready`. |

`summary`, `json` and `check_prompt_injection` cost 3 extra because a language model reads the page. A page pays the surcharge once, however many of the three you ask for.

## When you're charged

You're charged only when a request succeeds: a `200` with `"success": true`. You're never charged for:

* Failed requests (any 4xx or 5xx)
* Validation and authentication errors
* Rate-limit rejections (`429`) and timeouts (`504`)
* Crawl or batch pages that failed (`ok: false`)
* Monitor pages that couldn't be checked, and skipped checks

## Crawls and batches

Submitting a crawl or a batch is free. You pay for what it returns, as it completes:

* **You pay for pages fetched, not for `limit`.** A crawl capped at 500 pages that finds 12 costs 12 credits.
* **Polling is free.** Each status call bills only the pages that finished since your last call. Checking every five seconds costs the same as checking once at the end.
* **Webhooks don't change the price.** A job you only follow by webhook is charged when it ends.
* **Cancelling** charges for what was fetched before the job stopped.

A `/batch/{endpoint}` job your key can't pay for in full is refused when you submit it, and the error says how many URLs fit. See [Async jobs](/concepts/async-jobs) for how polling and results work.

## Searches

A search costs 2 credits per 10 results returned, rounded up: 10 results cost 2, and 11 to 20 cost 4. Result pages you ask to have scraped cost what [`/scrape`](/web-data/scrape) costs each. A page that couldn't be scraped is free.

## Monitors

Creating, reading, changing and deleting a [monitor](/monitors/overview) is free. Each check is billed to the API key that created the monitor, when the check finishes.

An hourly check of one page costs 1 credit, about 720 a month. Every monitor shows `estimated_credits_per_month`, an upper bound worked out the same way.

A check never spends more than your key has left. If credits run out partway, the check stops and reports `partial`. If the key has none, the check is recorded as `skipped_no_credits`, costs nothing, and the monitor resumes when credits refill. Pause a monitor to stop its charges and keep its history. See [Monitor limits and credits](/monitors/limits) for the details.

## Over MCP

The [MCP server](/mcp/overview) charges what the matching REST endpoint charges. `prefetch_enrich` costs 12 credits and `prefetch_scrape` costs 1. Tools that only manage or read work you already paid for are free:

* `prefetch_check_crawl_status` bills only the crawl or batch pages that finished since your last call.
* `prefetch_cancel_crawl` and `prefetch_logo_urls` never charge.
* The monitor tools never charge, except `prefetch_run_monitor`, which runs a check now.

MCP and REST calls share one request cache, so an agent's request can be answered from a page you already fetched. See [Caching](/concepts/caching).

## Plans

Every plan unlocks every endpoint. Plans differ in monthly credits and in how many requests can run at once.

| Plan | Price | Credits a month | Concurrent requests | Requests a minute |
| - | - | - | - | - |
| Free | \$0 | 1,000 | 1 | 30 |
| Starter | $11 a month, or $108 a year | 10,000 | 10 | No limit |
| Pro | $49 a month, or $490 a year | 75,000 | 50 | No limit |
| Growth | $149 a month, or $1,490 a year | 300,000 | 150 | No limit |
| Scale | $399 a month, or $3,990 a year | 1,000,000 | 500 | No limit |
| Enterprise | Custom | From 2,000,000 | Custom | No limit |

Paid plans have no per-minute cap. See [Rate limits](/concepts/rate-limits).

Compare plans on the [pricing page](https://prefetch.io/#pricing-section), and change plan from the [upgrade page](https://prefetch.io/upgrade). An upgrade applies straight away and is charged pro rata. Stripe shows what any change costs before you confirm it.

## Monthly refills

Your plan's credits refill every month. Unused monthly credits don't roll over.

| Plan | Refills on |
| - | - |
| Free | The day of the month you signed up |
| Paid plans | Each billing date. Annual plans refill on the same day every month. |

If your refill day is the 29th, 30th or 31st, credits refill on the last day of shorter months.

## Top-ups

There's no overage. When your credits run out, requests stop until they refill. On a paid plan you can buy top-up packs from the [billing page](https://prefetch.io/billing) at any time, several at once if you like:

| Plan | Pack |
| - | - |
| Starter | 2,500 credits for \$5 |
| Pro | 10,000 credits for \$10 |
| Growth | 35,000 credits for \$25 |
| Scale | 100,000 credits for \$50 |

Top-up credits arrive as soon as the payment completes. They're spent after your monthly credits, and they never expire: they carry over every refill and stay with you if you change plan.

## Credit limits per key

Each API key has a `credits_limit`: your monthly allowance plus any top-up credits. Once `credits_used` reaches it, requests fail with `CREDITS_EXHAUSTED` until your credits refill or you top up:

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": "Credit limit exceeded",
  "error_code": "CREDITS_EXHAUSTED",
  "retryable": false,
  "meta": { "requestId": "b9e1a2f3-4c5d-6e7f-8a9b-0c1d2e3f4a5b", "durationMs": 12 }
}
```

Watch your usage on the [dashboard](https://prefetch.io/dashboard).

## Choosing the cheapest call

| You need | Use | Credits |
| - | - | - |
| A domain from a company name | [`/resolve`](/company-data/resolve) | 1, or 3 with a live lookup |
| The merchant behind a card transaction | [`/transaction`](/company-data/transaction) | 3, or 1 for a repeat |
| Brand, company and industry together | [`/enrich`](/company-data/enrich) | 12, instead of 20 for three calls |
| Brand and company only | [`/enrich`](/company-data/enrich) | 12, instead of 15 for two calls |
| Only the industry | [`/classify`](/company-data/classify) | 5 |
| Logos to show in your UI | the [logo CDN](/company-data/logo-cdn) | 0, from a monthly quota |
| A site's design system | [`/styleguide`](/company-data/styleguide) | 10 |
| One page's content | [`/scrape`](/web-data/scrape) | 1 |
| Structured JSON from a page | [`/scrape`](/web-data/scrape) with `formats=json` | 4 |
| A site's URL list | [`/map`](/web-data/map) | 1 |
| 40 pages of a site | [`/crawl`](/web-data/crawl) | 40 |
| The same data for 300 domains | [`/batch/enrich`](/jobs/batches) | 12 per domain answered |
| To know when a page changes | a [monitor](/monitors/overview), checking hourly | about 720 a month |


# Error handling
Source: https://docs.prefetch.io/concepts/errors

How the Prefetch API reports errors: the error envelope, stable error codes, and when to retry.

## Error envelope

Errors use the same envelope as successful responses. `success` is `false`, `error` is a message for people, and two fields are for your code:

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": "The target URL could not be resolved. Please check the domain name.",
  "error_code": "DNS_RESOLUTION_FAILED",
  "retryable": false,
  "meta": {
    "requestId": "b9e1a2f3-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "durationMs": 412
  }
}
```

Branch on `error_code`, not on the wording of `error`, which can change. `retryable` tells you whether the same request can succeed later.

* **`error_code`** says what went wrong. Codes are stable: once published, a code keeps its meaning.
* **`retryable`** is `true` for capacity limits, timeouts and transient failures. It's `false` when the problem is the request or the target itself: a bad parameter, a domain that doesn't exist, a page that returns 404.

Authentication and rate-limit errors are answered before the request is processed. They carry `error`, `error_code` and `retryable`, but no `success` or `meta`:

```json theme={"theme":"css-variables"}
{
  "error": "Rate limit exceeded",
  "retryAfterSeconds": 12,
  "error_code": "RATE_LIMITED",
  "retryable": true
}
```

## Handling errors

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch(url, { headers: { "X-API-Key": process.env.PREFETCH_API_KEY } });
const body = await res.json();

if (res.ok) {
  // Use body.data
} else if (body.retryable) {
  // Wait (honor the Retry-After header when present), then send the same request again
} else if (body.error_code === "CREDITS_EXHAUSTED") {
  // Top up, or wait for the monthly refill
} else {
  // Retrying won't help: fix the request, or skip this URL
  console.error(`${body.error_code}: ${body.error}`);
}
```

```python Python theme={"theme":"css-variables"}
r = requests.get(url, params=params, headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]})
body = r.json()

if r.ok:
    data = body["data"]
elif body.get("retryable"):
    pass  # Wait (honor the Retry-After header when present), then send the same request again
elif body.get("error_code") == "CREDITS_EXHAUSTED":
    pass  # Top up, or wait for the monthly refill
else:
    print(f"{body['error_code']}: {body['error']}")  # Retrying won't help
```

## Error codes

### Your request

| Code | Status | Retryable | Meaning |
| - | - | - | - |
| `INVALID_REQUEST` | 400 | No | A parameter is missing or invalid. The message names it. |
| `PAYLOAD_TOO_LARGE` | 413 | No | The request body is over 1 MB. |
| `NOT_FOUND` | 404 | No | No such crawl, batch, monitor or check. It may have expired, or belong to another key. |
| `CONFLICT` | 409 | Yes | A monitor check is already queued or running. Retry when it finishes. |

### Your account

| Code | Status | Retryable | Meaning |
| - | - | - | - |
| `UNAUTHORIZED` | 401, 403 | No | No API key, or the key is unknown, revoked, expired or not live. |
| `CREDITS_EXHAUSTED` | 403 | No | The key has used its credits. Requests work again after a top-up or the [monthly refill](/concepts/credits#monthly-refills). |
| `FORBIDDEN` | 403 | No | The key can't use this feature. For example, monitors need a direct Prefetch API key, not a RapidAPI subscription. |
| `RATE_LIMITED` | 429 | Yes | Too many requests this minute. Wait `retryAfterSeconds`. See [Rate limits](/concepts/rate-limits). |
| `CONCURRENCY_LIMITED` | 429 | Yes | The key already has as many requests running as its plan allows (`limit`). Retry when one finishes. |

### The target URL

| Code | Status | Retryable | Meaning |
| - | - | - | - |
| `URL_BLOCKED` | 403 | No | The URL is on your key's blocklist. |
| `URL_NOT_PERMITTED` | 403 | No | The URL, or a page it redirected to, points at a private or reserved address. |
| `DNS_RESOLUTION_FAILED` | 422 | No | The domain doesn't resolve. Check the spelling. |
| `TARGET_BLOCKED` | 403 | No | The site refused automated access, or redirected to a search engine or a consent page on another domain. |
| `TARGET_CONNECTION_FAILED` | 502 | Yes | The site refused or dropped the connection. |
| `TARGET_TIMEOUT` | 504 | Yes | The site didn't respond in time. |
| `TARGET_SSL_ERROR` | 502 | No | The site's TLS certificate is invalid or expired. |
| `TARGET_SERVER_ERROR` | 502 | Yes | The site answered with a 5xx error. |
| `TARGET_CLIENT_ERROR` | 502 | No | The site answered with a 4xx error, such as 404. The message includes the status. |
| `TARGET_NOT_A_PAGE` | 422 | No | The URL is a file download, not a web page. |
| `NO_LINKS_FOUND` | 422 | No | `/map` found no links to the site's own pages, on the page or in a sitemap. Common on pages that build their links with JavaScript after user input. |
| `TARGET_UNLOADABLE` | 502 | No | The site's response couldn't be loaded as a page. |
| `TARGET_ELEMENT_NOT_FOUND` | 422 | No | `/screenshot` with `selector`: no element matched within 10 seconds. |

### This service

| Code | Status | Retryable | Meaning |
| - | - | - | - |
| `TIMEOUT` | 504 | Yes | The request didn't finish within its time limit (55 seconds for most endpoints). |
| `SERVICE_BUSY` | 503 | Yes | Prefetch is under heavy load. Retry after the `Retry-After` header. |
| `SERVICE_UNAVAILABLE` | 503 | Yes | A component is briefly unavailable. The [status page](https://prefetch.betteruptime.com/) shows current incidents. |
| `RESEARCH_INCONCLUSIVE` | 500 | No | [`/answers`](/web-data/answers) found no usable evidence. Rephrase the task, or name the site to research. |
| `INTERNAL_ERROR` | 500 | Yes | Something failed on our side. Retry once. If it keeps happening, [contact support](mailto:hi@prefetch.io) with the `requestId`. |

> [!NOTE]
>
> You're never charged for a failed request.

## Errors on crawled pages

A crawl or batch doesn't fail when one page does. Each page in `GET /crawl/{id}`, and in `crawl.page` webhooks, carries `ok`. A failed page carries an `error_code` from the same list:

```json theme={"theme":"css-variables"}
{
  "url": "https://example.com/pricing",
  "depth": 1,
  "status_code": null,
  "ok": false,
  "error": "Failed to load page (HTTP 503)",
  "error_code": "TARGET_SERVER_ERROR"
}
```

Use it to decide what to try again. `TARGET_SERVER_ERROR` and `TARGET_TIMEOUT` often succeed later. `DNS_RESOLUTION_FAILED` never will.

## Blocked URLs

Some URLs are refused before any request is made:

* **Private and reserved addresses**, such as `10.x.x.x`, `192.168.x.x`, `127.x.x.x` and `169.254.x.x`. This includes domains that resolve to them and redirects that lead to them (`URL_NOT_PERMITTED`).
* **Bare IP addresses and reserved TLDs**, such as `.local`, `.internal` and `.localhost` (`INVALID_REQUEST`).
* **Your key's blocklist** (`URL_BLOCKED`).

Still stuck? See [Troubleshooting](/concepts/troubleshooting).


# Production checklist
Source: https://docs.prefetch.io/concepts/production-checklist

What to check before you send real traffic to Prefetch: keys, errors, retries, concurrency, timeouts, webhooks and costs.

Test three cases before you launch: a site that works, a site that can't be read, and a result with missing fields. Then work through this list.

## Keys

* [ ] Keys live on your server or in a secret store, never in browser code or a repository.
* [ ] Development and production use separate keys.
* [ ] Each key has a credit limit, so a bug can't spend your whole balance.
* [ ] Browser-side logos use the [logo CDN](/company-data/logo-cdn) token, not your API key.

## Errors and retries

* [ ] Your code branches on `error_code`, not on the `error` message.
* [ ] You retry only when `retryable` is `true`, with exponential backoff, and you honor `Retry-After`.
* [ ] Missing fields are handled. Curated and live answers can differ, and many fields can be `null`.

See [Error handling](/concepts/errors).

## Throughput

* [ ] Parallel requests stay at or under your plan's [concurrency limit](/concepts/rate-limits).
* [ ] Lists of more than a few dozen URLs go through a [batch](/jobs/batches), not a loop.
* [ ] Your HTTP client allows at least 60 seconds per request. Most endpoints finish within 55.

## Webhooks

* [ ] Your handler verifies `X-Prefetch-Signature` against the raw body.
* [ ] It answers `2xx` within 10 seconds and does slow work afterward.
* [ ] It skips deliveries it has already handled.

See [Webhooks](/concepts/webhooks).

## Costs

* [ ] You store brand and company data instead of fetching it on every page view. See [Caching](/concepts/caching).
* [ ] Each monitor's `estimated_credits_per_month` fits your budget, and monitors you don't need are paused.
* [ ] Crawls have a sensible `limit` and `include_paths`.

## Content from the web

* [ ] If page text reaches a language model, treat it as untrusted. Turn on `check_prompt_injection` for pages you don't control. See [Security](/concepts/security).

## Observability

* [ ] You log `meta.requestId`, the status and the `error_code` for every failed call.
* [ ] Someone watches the [changelog](/changelog), and your on-call team subscribes to the [status page](https://prefetch.betteruptime.com/).


# Rate limits
Source: https://docs.prefetch.io/concepts/rate-limits

How many requests each Prefetch plan can run at once, and how to handle 429 responses.

Prefetch limits how many requests your API key can have **running at the same time**. Paid plans have no per-minute cap: as soon as one request finishes, the next one can start.

| Plan | Price | Credits a month | Concurrent requests | Requests a minute |
| - | - | - | - | - |
| Free | \$0 | 1,000 | 1 | 30 |
| Starter | $11 a month, or $108 a year | 10,000 | 10 | No limit |
| Pro | $49 a month, or $490 a year | 75,000 | 50 | No limit |
| Growth | $149 a month, or $1,490 a year | 300,000 | 150 | No limit |
| Scale | $399 a month, or $3,990 a year | 1,000,000 | 500 | No limit |
| Enterprise | Custom | From 2,000,000 | Custom | No limit |

Going over a limit returns `429 Too Many Requests`. A refused request costs no credits.

## Concurrency limit

Each key can have a fixed number of requests in flight. A request that would go over it is refused straight away with `429`. It isn't queued.

```json theme={"theme":"css-variables"}
{
  "error": "Concurrency limit exceeded — too many requests in flight",
  "limit": 50,
  "error_code": "CONCURRENCY_LIMITED",
  "retryable": true
}
```

Every response that counts toward the limit carries two headers, so you can pace yourself:

| Header | Meaning |
| - | - |
| `X-Concurrency-Limit` | How many requests this key can run at once |
| `X-Concurrency-Running` | How many are running now, including this one |

The simplest way to stay under the limit is a worker pool the size of your plan's limit. Each worker sends its next request when its last one finishes.

For hundreds of URLs, a [batch](/jobs/batches) is easier: one request, and Prefetch manages the concurrency for you.

## Per-minute limit

The Free plan allows **30 requests a minute**, counted over a sliding 60-second window. Paid plans have a high safety ceiling that stops runaway loops, which ordinary traffic never reaches. Going over either one returns:

```json theme={"theme":"css-variables"}
{
  "error": "Rate limit exceeded",
  "retryAfterSeconds": 12,
  "error_code": "RATE_LIMITED",
  "retryable": true
}
```

The response has a `Retry-After` header in seconds, plus `X-RateLimit-Limit` and `X-RateLimit-Remaining`.

## Requests without an API key

Requests with no API key or token are limited to 300 a minute per IP address. If one IP address sends 60 unknown API keys or invalid tokens in a minute, it's refused with `429` and a `Retry-After` header for the rest of that minute. Requests with a valid key never count toward either limit.

## Handling 429 responses

Wait for `Retry-After` when it's there, and back off exponentially when it isn't:

```javascript Node.js theme={"theme":"css-variables"}
async function fetchWithRetry(url, options, maxRetries = 4) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fetch(url, options);
    if (res.status !== 429 || attempt === maxRetries) return res;

    const retryAfter = Number(res.headers.get("Retry-After"));
    const waitMs = retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 1000; // 1s, 2s, 4s, 8s
    await new Promise((resolve) => setTimeout(resolve, waitMs));
  }
}
```

```python Python theme={"theme":"css-variables"}
import time
import requests

def fetch_with_retry(url, params, headers, max_retries=4):
    for attempt in range(max_retries + 1):
        r = requests.get(url, params=params, headers=headers)
        if r.status_code != 429 or attempt == max_retries:
            return r

        retry_after = r.headers.get("Retry-After")
        time.sleep(int(retry_after) if retry_after else 2 ** attempt)  # 1s, 2s, 4s, 8s
```

## Staying within limits

* **Use `/enrich`** instead of separate `/brand`, `/company` and `/classify` calls. It's one request instead of three.
* **Cache what doesn't change.** Brand and company data is stable for days. See [Caching](/concepts/caching).
* **Don't fetch the same domain twice** in a short window.
* **Match your plan's concurrency.** Run as many requests in parallel as your plan allows, and no more. Extra requests are refused, not queued.


# Security and data handling
Source: https://docs.prefetch.io/concepts/security

How Prefetch protects your account, which sites it will and won't fetch, how it treats robots.txt, and how long results are kept.

## Your account

* **API keys** stay on your server. Each key can have an expiry date and a credit limit, and you can revoke it on the [dashboard](https://prefetch.io/dashboard). See [Authentication](/concepts/authentication).
* **Connected apps** such as Claude and ChatGPT sign in with OAuth. A connected app can call every tool as you, and its calls use your credits. It can't see your password, payment details or API keys, and it can't change your plan. Disconnect it under **Connected Apps** and its next call fails.
* **The logo token** is publishable. It serves logo images and nothing else. Rotate it if someone else is using your quota.

## What Prefetch won't fetch

* **Private and reserved addresses.** Requests to `10.x.x.x`, `192.168.x.x`, `127.x.x.x`, `169.254.x.x` and similar ranges are refused, including domains that resolve to them and redirects that lead to them.
* **Bare IP addresses and reserved TLDs** such as `.local` and `.internal`.
* **URLs on your key's blocklist.**

See [Blocked URLs](/concepts/errors#blocked-urls).

## robots.txt

[Crawls](/web-data/crawl) obey `robots.txt` by default: both `Disallow` rules and `Crawl-delay`. You can turn that off with `respect_robots_txt: false`. `/map` reads `robots.txt` only to find sitemaps, and fetches at most one page of the site.

## Untrusted page content

Pages are written by strangers, and much of what Prefetch returns ends up in front of a language model. Set `check_prompt_injection=true` on [`/scrape`](/web-data/scrape#prompt-injection-check), crawls and batch scrapes, and a model checks the page for text aimed at AI assistants. The page is still returned, with a verdict you can act on.

Monitor goals are judged the same way: page content is treated as data, never as instructions.

## Language models

`summary`, `json`, the prompt-injection check, monitor judging, `/transaction` and `/answers` use a language model to read page text. Every other format is the page itself.

## How long results are kept

| Data | Kept for |
| - | - |
| Crawl and batch results | Until the job's `expires_at`, 24 hours after it was created |
| Monitor checks and snapshots | The monitor's `retention_days`: 30 by default, up to 365 on paid plans |
| Stored page copies used by `max_age` | Up to 30 days. Requests that send `headers` are never stored. |
| `/scrape` screenshots | A short-lived URL. Copy the image if you need to keep it. |
| Webhook secrets for crawls and batches | Shown once, in the response that creates the job |

Deleting a monitor deletes its checks, snapshots and pending webhook deliveries.

## Reporting a security issue

Email [hi@prefetch.io](mailto:hi@prefetch.io). Please don't open a public issue.


# Troubleshooting
Source: https://docs.prefetch.io/concepts/troubleshooting

Fixes for the most common Prefetch problems: auth errors, 429s, empty pages, small crawls, missing webhooks and noisy monitors.

If many requests fail at once, check the [status page](https://prefetch.betteruptime.com/) first.

Start with the response. Every error carries an `error_code` and a `retryable` flag, and every response carries `meta.requestId`. Quote the `requestId` if you [contact support](mailto:hi@prefetch.io).

## Authentication

| You see | Fix |
| - | - |
| `401` `"API key required"` | Send the key in the `X-API-Key` header. REST endpoints don't read `Authorization: Bearer`. Only `/mcp` does. |
| `403` `"Invalid API key"` | The key isn't the one on your [dashboard](https://prefetch.io/dashboard). Check the environment variable your code actually reads. |
| `403` `CREDITS_EXHAUSTED` | The key has used its credits. [Top up](/concepts/credits#top-ups) or wait for the refill. |
| `403` `FORBIDDEN` | The key can't use this feature. Monitors, for example, need a direct Prefetch key, not a RapidAPI subscription. Webhooks, MCP and the logo CDN aren't available through RapidAPI either. |

## Too many requests

| You see | Fix |
| - | - |
| `429` `CONCURRENCY_LIMITED` | More requests are running than your plan allows. Run fewer in parallel, or send one [batch](/jobs/batches) instead. |
| `429` `RATE_LIMITED` | Free plan, over 30 a minute. Wait `retryAfterSeconds`. |

See [Rate limits](/concepts/rate-limits).

## A page comes back empty or incomplete

* **The content loads late.** Add `wait_for` (milliseconds) or `wait_for_selector` so the page finishes rendering first.
* **The main content was hard to find.** A `warnings` entry says the full page body was returned instead. Name the content with `include_selectors`, or drop clutter with `exclude_selectors`.
* **The site blocks bots** (`TARGET_BLOCKED`). Retrying won't help. Some sites refuse every automated request.
* **It's a file, not a page** (`TARGET_NOT_A_PAGE`). PDFs are read as documents. Other downloads aren't.
* **`summary` or `json` is `null`.** The language model step failed on its own. The reason is in `warnings`, and the rest of the scrape is still there.
* **A `json` field is `null`.** The value isn't on the page. Prefetch never fills fields in from a model's own knowledge.

## A crawl returns fewer pages than expected

Call [`GET /crawl/{id}/errors`](/api-reference/endpoint/crawl-errors). It counts every skipped URL by reason:

| Large count | Usually means |
| - | - |
| `limit` | The crawl ran out of budget. Raise `limit`. |
| `out-of-scope` | Links pointed above the start URL's path. Set `crawl_entire_domain: true`. |
| `depth` | Pages are deeper than `max_depth`. Raise it, or seed from the sitemap. |
| `not-included`, `excluded` | Your `include_paths` or `exclude_paths` patterns are too strict. They match the path and query, not the hostname. |
| `robots` | The site's `robots.txt` disallows them. |

## `/map` fails with `NO_LINKS_FOUND`

The page links to none of the site's own pages, and no sitemap lists any. This is common on apps that build their links with JavaScript after user input. Try `sitemap=only`, or map a different page on the site.

## Webhooks don't arrive

* The URL must be public and use `https://`. `localhost` never works. Use a tunnel while you develop.
* Answer with a `2xx` within 10 seconds, and do slow work after you respond.
* Webhooks aren't available through RapidAPI keys.
* Missed one? The status endpoint always has every result. See [Webhooks](/concepts/webhooks).

## A monitor is noisy or quiet

| Problem | Fix |
| - | - |
| Alerts for timestamps, counters or rotating banners | Use `ignore_text`, `ignore_dates` or `exclude_selectors`. See [cutting noise](/monitors/change-detection#cutting-noise). |
| You only care about a few facts | Switch the target to `json` mode and track just those fields. |
| No alerts on the first check | Expected. The first check records a baseline. Changes show from the second check. |
| Changes are recorded but not sent | The judge ruled them not meaningful for your goal. Read `judgment.reason` on the check, and sharpen the [goal](/monitors/goals). |
| Checks say `skipped_no_credits` | The key that created the monitor ran out of credits. The monitor resumes when they refill. |

## Logos show a letter mark

The logo CDN shows a letter mark while it looks a new domain's logo up in the background. The next request usually has the real logo. Use `fallback=404` or `fallback=transparent` to handle it yourself.

## Still stuck?

Email [hi@prefetch.io](mailto:hi@prefetch.io) with the `requestId`, the request you sent, and what you expected.


# Webhooks
Source: https://docs.prefetch.io/concepts/webhooks

Get crawl, batch and monitor results pushed to you: events, payloads, signature verification and retries.

Crawls, batches and monitors can POST their results to your server as they happen, so you don't have to poll. This page covers what every Prefetch webhook has in common.

## Events

| Source | Events | Set up with |
| - | - | - |
| [Crawl](/web-data/crawl) | `crawl.started`, `crawl.page`, `crawl.completed`, `crawl.failed` | `webhook` on `POST /crawl` |
| [Batch scrape](/jobs/batches) | `batch_scrape.started`, `batch_scrape.page`, `batch_scrape.completed`, `batch_scrape.failed` | `webhook` on `POST /batch/scrape` |
| [Batch](/jobs/batches) | `batch_<endpoint>.started`, `.page`, `.completed` and `.failed`, for example `batch_enrich.page` | `webhook` on `POST /batch/{endpoint}` |
| [Monitor](/monitors/alerts) | [`monitor.page`](/api-reference/endpoint/monitor-webhook-page), [`monitor.check.completed`](/api-reference/endpoint/monitor-webhook-check) | `webhook` on `POST /monitor` |

A `.page` event carries one result: a crawled page, or one URL's answer in a batch. Failed pages are sent too, with `ok: false`.

## Configure a webhook

Pass an `https://` URL, or an object:

```json theme={"theme":"css-variables"}
{
  "webhook": {
    "url": "https://example.com/hooks/prefetch",
    "events": ["page", "completed"],
    "headers": { "Authorization": "Bearer your-token" },
    "metadata": { "job": "docs-sync" }
  }
}
```

| Field | Meaning |
| - | - |
| `url` | Where to POST. It must be a public `https://` address. |
| `events` | Which events to send. Leave it out to get all of them. Crawls and batches take short names (`page`, `completed`); monitors take full names (`monitor.page`). |
| `headers` | Sent with every delivery. Use them to authenticate Prefetch to your server. |
| `metadata` | Echoed back in every payload, up to 4 KB. Use it to tie a delivery to your own job. |

Webhooks aren't available through RapidAPI, which can only bill a response. Poll the status endpoint instead.

## Payload

Crawl and batch deliveries share one envelope:

```json theme={"theme":"css-variables"}
{
  "success": true,
  "type": "crawl.page",
  "id": "whd_3f9a1c7e5b2d4f6a8c0e1b3d",
  "created_at": "2026-10-11T09:14:09.512Z",
  "crawl_id": "crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e",
  "data": { "url": "https://docs.stripe.com/payments", "ok": true, "markdown": { "content": "# Payments..." } },
  "metadata": { "job": "docs-sync" }
}
```

`data` is the same object the status endpoint returns for that page. Monitor payloads are described on the [`monitor.page`](/api-reference/endpoint/monitor-webhook-page) and [`monitor.check.completed`](/api-reference/endpoint/monitor-webhook-check) pages.

## Verify signatures

Every delivery carries an `X-Prefetch-Signature` header:

```
X-Prefetch-Signature: t=1760248862,v1=5f2b8c1e...
```

`v1` is the hex HMAC-SHA256 of `<t>.<raw request body>`, keyed with the webhook's secret. The timestamp is signed too, so a captured request can't be replayed with a fresh header. Reject anything older than five minutes.

Verify against the **raw** body, before you parse the JSON. Re-serializing it changes the bytes and breaks the signature.

```javascript Node.js (Express) theme={"theme":"css-variables"}
import crypto from "node:crypto";
import express from "express";

const app = express();

app.post("/hooks/prefetch", express.raw({ type: "application/json" }), (req, res) => {
  const header = req.get("X-Prefetch-Signature") || "";
  const { t, v1 } = Object.fromEntries(header.split(",").map((kv) => kv.split("=")));

  const fresh = Math.abs(Date.now() / 1000 - Number(t)) <= 300;
  const expected = crypto
    .createHmac("sha256", process.env.PREFETCH_WEBHOOK_SECRET)
    .update(`${t}.${req.body}`)
    .digest();
  const given = Buffer.from(v1 || "", "hex");

  if (!fresh || given.length !== expected.length || !crypto.timingSafeEqual(given, expected)) {
    return res.status(401).send("invalid signature");
  }

  const event = JSON.parse(req.body);
  res.sendStatus(200); // acknowledge first, then do the work
  handle(event);
});
```

```python Python (Flask) theme={"theme":"css-variables"}
import hashlib, hmac, os, time
from flask import Flask, request, abort

app = Flask(__name__)

@app.post("/hooks/prefetch")
def prefetch_webhook():
    header = request.headers.get("X-Prefetch-Signature", "")
    parts = dict(kv.split("=", 1) for kv in header.split(",") if "=" in kv)
    t, v1 = parts.get("t", "0"), parts.get("v1", "")

    expected = hmac.new(
        os.environ["PREFETCH_WEBHOOK_SECRET"].encode(),
        f"{t}.".encode() + request.get_data(),
        hashlib.sha256,
    ).hexdigest()

    if abs(time.time() - int(t)) > 300 or not hmac.compare_digest(v1, expected):
        abort(401)

    event = request.get_json()
    # ... handle the event
    return "", 200
```

### Where the secret comes from

| Source | Secret |
| - | - |
| Crawl or batch | `webhook.secret` in the `POST` response. That's the only place it appears, so store it. |
| Monitor | `webhook.secret` on the monitor. Read it again with [`GET /monitor/{id}`](/api-reference/endpoint/monitor-get), and replace it with `"rotate_secret": true` on [`PATCH /monitor/{id}`](/api-reference/endpoint/monitor-update#rotating-the-signing-secret). |

## Respond and retry

Answer with any `2xx` within **10 seconds**, then do slow work afterward. A timeout, a `4xx` or `5xx`, or a redirect counts as a failure and is retried:

| Source | Retries | Then |
| - | - | - |
| Crawl and batch | After 2, 10 and 30 seconds | The delivery is dropped |
| Monitor | After 1, 5 and 15 minutes | The delivery is marked failed |

Crawl and batch deliveries go out in order. Monitor retries carry the same `id`, also sent as the `X-Prefetch-Delivery` header, so store the ids you've handled and skip repeats.

Webhooks are a notification, not the record. The status endpoint always has every page, and a monitor's checks are readable with [`GET /monitor/{id}/checks/{checkId}`](/api-reference/endpoint/monitor-check).

## Monitor headers

| Header | Value |
| - | - |
| `X-Prefetch-Event` | The event name, such as `monitor.page` |
| `X-Prefetch-Delivery` | The delivery id, the same as `id` in the body |
| `X-Prefetch-Signature` | `t=<unix seconds>,v1=<hex HMAC-SHA256>` |
| `User-Agent` | `Prefetch-Webhooks/1.0` |

Any `headers` you set on the webhook are sent as well.

## Testing locally

Prefetch only calls public `https://` addresses, so `localhost` won't work. Use a tunnel such as ngrok or Cloudflare Tunnel, or a request inspector, while you build your handler.


# Prefetch API
Source: https://docs.prefetch.io/index

One API for the company behind any website and the pages on it: brand, logos, industry, contacts, clean markdown, search, and alerts when pages change.

Prefetch turns any website into data you can use:

* **The company behind it:** brand colors and logos, legal name, contacts, industry and design system.
* **The pages on it:** clean markdown, structured JSON, screenshots, every URL, or the whole site.
* **What changes on it:** monitors that tell you, by webhook or email, when a page changes in a way you care about.

One API key covers all of it, over REST or [MCP](/mcp/overview). Failed requests are never charged, and the [Free plan](/concepts/credits#plans) includes 1,000 credits a month.

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/enrich?url=stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "brand": { "colors": { "brand_colors": [{ "hex": "#635BFF", "name": "Medium Slate Blue" }] }, "logos": { "primary": { "url": "https://curated.prefetch.io/…/primary.svg" } } },
    "company": { "name": "Stripe, Inc.", "foundedYear": 2010, "emails": ["support@stripe.com"] },
    "classification": { "category": "Business", "subcategory": "Business Software" }
  }
}
```

> [card] [Quickstart](/quickstart)
>
> Get a key and make your first call in under 5 minutes.

> [card] [Connect an agent](/mcp/overview)
>
> Give Claude, ChatGPT or Cursor these tools over MCP. Nothing to install.

## Choose an endpoint

| You have | You want | Use | Credits |
| - | - | - | - |
| A company name | Its website | [Resolve](/company-data/resolve) | 1 |
| A card transaction line | The merchant, with its logo | [Card transactions](/company-data/transaction) | 3 |
| A domain | Brand, company and industry in one call | [Enrich](/company-data/enrich) | 12 |
| A domain | Colors, logos and fonts | [Brand](/company-data/brand) | 10 |
| A domain | Legal name, emails and addresses | [Company](/company-data/company) | 5 |
| A domain | Its IAB industry | [Classify](/company-data/classify) | 5 |
| A domain | Its design system, as CSS and Tailwind | [Styleguide](/company-data/styleguide) | 10 |
| A list of domains | Logos to show in your UI | [Logo CDN](/company-data/logo-cdn) | 0 |
| A URL | The page as markdown or JSON | [Scrape](/web-data/scrape) | 1 |
| A URL | A screenshot | [Screenshots](/web-data/screenshot) | 1 |
| A search query | Ranked results, with their text | [Search](/web-data/search) | 2 per 10 |
| A question | A sourced answer in your JSON shape | [Answers](/web-data/answers) | 10 |
| A site | Every URL on it | [Map](/web-data/map) | 1 |
| A site | Every page as markdown | [Crawl](/web-data/crawl) | 1 per page |
| Hundreds of URLs | Scrape, enrich, brand, screenshot and more, as one job | [Batches](/jobs/batches) | Per URL |
| Pages you care about | An alert when they change | [Monitors](/monitors/overview) | 1 per page checked |

See [Credits](/concepts/credits) for the full price list.

Coming from Firecrawl, Context.dev, Clearbit or Brandfetch? See how [Prefetch compares](/compare/overview), and the migration guides.

## Build something

> [card] [Enrich signups](/recipes/enrich-signups)
>
> Prefill a profile from a work email.

> [card] [Merchant feed](/recipes/merchant-feed)
>
> Readable card transactions with logos.

> [card] [Competitor pricing](/recipes/competitor-pricing)
>
> Get told when a rival changes its prices.

> [card] [On-brand UI](/recipes/on-brand-ui)
>
> Build UI that matches any site.

> [card] [Company directory](/recipes/company-directory)
>
> Hundreds of companies, with logos.

> [card] [Docs to markdown](/recipes/docs-to-markdown)
>
> Feed a whole docs site to an LLM.


# Clay
Source: https://docs.prefetch.io/integrations/clay

Resolve, enrich and classify Clay rows with Prefetch HTTP API columns: domains from names, industry, logos, brand colors, emails and social profiles.

Clay's **HTTP API** enrichment calls any API once per row and lets you map fields from the response into columns. Each recipe below is one HTTP API column.

## Set up the column

In your table: **Add enrichment → HTTP API**. Then, for every recipe:

1. **Method** and **Endpoint** as given below. Type `/` in the endpoint to insert a column's value.
2. **Headers**: key `X-API-Key`, value your Prefetch API key.
3. **Run on a few rows**, then choose **fields to return**: Clay lists the response's fields, and each one you pick becomes its own column.
4. **Rate limit**: keep requests in flight within your plan's concurrency. That's 1 at a time on Free (30 a minute), and up to 10 at a time on Starter. Rows that hit the limit fail with `CONCURRENCY_LIMITED` and can simply be re-run; failures are never charged.

## Company name → domain

Most lead lists start with names. `/resolve` turns them into domains, which every other recipe needs.

| Setting | Value |
| - | - |
| Method | `GET` |
| Endpoint | `https://api.prefetch.io/resolve?live=true&name=` + `/Company Name` |

| Field | Response path |
| - | - |
| Domain | `data.results[0].domain` |
| Confidence | `data.results[0].confidence` |

Treat a confidence of **0.8 or above** as the answer. Add a Clay condition to only run the next columns when it is, and review the rest. 1 credit per row from the index, 3 when the live lookup runs.

## Domain → full company profile

One `/enrich` call gives brand, company and industry together: cheaper than three separate calls.

| Setting | Value |
| - | - |
| Method | `GET` |
| Endpoint | `https://api.prefetch.io/enrich?url=` + `/Domain` |

| Field | Response path |
| - | - |
| Company name | `data.company.name` |
| Industry | `data.classification.category` |
| Sub-industry | `data.classification.subcategory` |
| One-line description | `data.classification.tagline_description` |
| Description | `data.classification.description` |
| Logo | `data.brand.logos.primary.url` |
| Brand color | `data.brand.colors.brand_colors[0].hex` |
| Contact emails | `data.company.emails` |
| LinkedIn | `data.company.social_links.linkedin` |
| X / Twitter | `data.company.social_links.twitter` |
| Stock tickers | `data.classification.stock_tickers` |

12 credits per row. Well-known companies are answered from curated data in milliseconds; others take 5–20 seconds while the site is read.

## Industry only, for ICP scoring

When all you need is the segment, `/classify` costs less than half of `/enrich`.

| Setting | Value |
| - | - |
| Method | `GET` |
| Endpoint | `https://api.prefetch.io/classify?url=` + `/Domain` |

Map `data.classification.category` (the IAB category, such as *Business*), `data.classification.subcategory` and `data.classification.iab_id`. 5 credits per row.

## Logos without an API call

For a logo to look at, you don't need a column that calls the API at all. Get your publishable token once:

```bash theme={"theme":"css-variables"}
curl https://api.prefetch.io/logo/token -H "X-API-Key: $PREFETCH_API_KEY"
```

Then add a **formula** column:

```
"https://logo.prefetch.io/" + {{Domain}} + "?token=pk_YOUR_TOKEN&size=128"
```

and set its type to **image**. Logos cost no credits (each plan includes a monthly quota of them), and a domain without a known logo shows a letter mark. See [Logo CDN](/company-data/logo-cdn).

## Thousands of rows

Clay calls the API once per row, so a large table is many requests at your plan's concurrency. When you only need the data once, an alternative is one [batch](/jobs/batches): export the domains, send them to `POST /batch/enrich`, and import the results from `GET /batch/enrich/{id}`. Each domain costs the same 12 credits either way.


# Make
Source: https://docs.prefetch.io/integrations/make

Build Make scenarios that enrich spreadsheet rows, name card transactions and receive batch results with the HTTP module.

Make reaches Prefetch through the **HTTP → Make a request** module.

## Enrich new rows in a Google Sheet

**1. Google Sheets → Watch New Rows** on a sheet with a domain column.

**2. HTTP → Make a request**

| Field | Value |
| - | - |
| URL | `https://api.prefetch.io/enrich` |
| Method | `GET` |
| Headers | `X-API-Key`: your Prefetch API key |
| Query String | `url`: the domain column from step 1 |
| Parse response | **Yes** |
| Timeout | `60` |

Run the module once so Make learns the response's structure; its fields then appear in the mapping panel under **Data**.

**3. Google Sheets → Update a Row**, row number from step 1, mapping for example:

| Column | Map |
| - | - |
| Company | `data.company.name` |
| Industry | `data.classification.category` |
| Description | `data.classification.tagline_description` |
| Logo | `data.brand.logos.primary.url` |
| Brand color | `first(map(data.brand.colors.brand_colors; "hex"))` |
| LinkedIn | `data.company.social_links.linkedin` |

12 credits per row.

> [!TIP]
>
> Set the scenario's **maximum number of cycles** and the HTTP module's **sequential processing** so no more requests run at once than your plan's concurrency allows (1 on Free, 10 on Starter).

## Name the merchant on card transactions

The same scenario shape, with the HTTP module pointed at `/transaction`:

| Field | Value |
| - | - |
| URL | `https://api.prefetch.io/transaction` |
| Method | `GET` |
| Headers | `X-API-Key`: your Prefetch API key |
| Query String | `descriptor`: the statement line · `country`: `US` |
| Parse response | **Yes** |

Map `data.kind`, `data.merchant.name`, `data.merchant.domain`, `data.category` and `data.logo_url`. 3 credits per line, 1 for a line looked up in the last 7 days.

## Retrying what can be retried

Add an error handler to the HTTP module: right-click → **Add error handler → Resume** (or **Break** with automatic retries). Prefetch's error body says whether a retry can help:

* `retryable: true` (`SERVICE_BUSY`, `CONCURRENCY_LIMITED`, `TIMEOUT`, `TARGET_TIMEOUT`): retry after a pause.
* `retryable: false` (`DNS_RESOLUTION_FAILED`, `TARGET_BLOCKED`, `INVALID_REQUEST`): record the error and move on.

Failed requests are never charged.

## Batches with a webhook

For hundreds of domains at once, start a [batch](/jobs/batches) and let Prefetch call your scenario back:

1. Create a scenario starting with **Webhooks → Custom webhook**, and copy its address.

2. From another scenario (or once, by hand), send `POST https://api.prefetch.io/batch/enrich` with the body:

   ```json theme={"theme":"css-variables"}
   {
     "urls": ["stripe.com", "linear.app", "notion.so"],
     "webhook": { "url": "YOUR_MAKE_WEBHOOK_ADDRESS", "events": ["page"] }
   }
   ```

3. Each `batch_enrich.page` event arrives as one bundle in the first scenario, with the domain's result under `data`: map it into your sheet or CRM.

Each domain costs 12 credits; failed ones are free. Webhooks are not available through RapidAPI keys.


# n8n
Source: https://docs.prefetch.io/integrations/n8n

Four n8n workflows to paste into your editor: enrich a list of domains, run a batch that resumes on its webhook, search and summarize the web, and name card-transaction merchants.

n8n workflows are JSON: **copy one of the workflows below and paste it into an empty canvas** (Ctrl+V / ⌘V). Each uses n8n's core nodes only: Code, HTTP Request, Edit Fields, Split Out and Wait.

## Add your API key once

Every HTTP Request node uses a **Header Auth** credential named `Prefetch API key`. Create it the first time you open a pasted workflow: double-click an HTTP Request node → **Credential → Create new**:

| Field | Value |
| - | - |
| Name | `X-API-Key` |
| Value | your Prefetch API key |

Name the credential `Prefetch API key` and the other templates pick it up.

## Enrich a list of domains

Enriches each domain with brand, company and industry data, and keeps the fields a CRM usually wants. Replace the **Domains** node with your source: a Google Sheet, your CRM, a webhook. The HTTP node sends one request at a time (raise the batch size up to your plan's concurrency) and retries what can be retried. 12 credits per domain.

```json enrich-domains.json theme={"theme":"css-variables"}
{
  "name": "Prefetch: Enrich a list of domains",
  "nodes": [
    {
      "parameters": {},
      "id": "6d0f4c2a-1b3e-4f5a-9c7d-0e1f2a3b4c01",
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [
        0,
        0
      ]
    },
    {
      "parameters": {
        "jsCode": "// Replace with your own source: a Google Sheet, a CRM, a webhook…\nreturn ['stripe.com', 'linear.app', 'notion.so'].map((domain) => ({ json: { domain } }));"
      },
      "id": "6d0f4c2a-1b3e-4f5a-9c7d-0e1f2a3b4c02",
      "name": "Domains",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        220,
        0
      ]
    },
    {
      "parameters": {
        "url": "https://api.prefetch.io/enrich",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "url",
              "value": "={{ $json.domain }}"
            }
          ]
        },
        "options": {
          "timeout": 60000,
          "batching": {
            "batch": {
              "batchSize": 1,
              "batchInterval": 0
            }
          }
        }
      },
      "id": "6d0f4c2a-1b3e-4f5a-9c7d-0e1f2a3b4c03",
      "name": "Prefetch enrich",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        440,
        0
      ],
      "retryOnFail": true,
      "maxTries": 3,
      "waitBetweenTries": 5000,
      "credentials": {
        "httpHeaderAuth": {
          "id": "",
          "name": "Prefetch API key"
        }
      }
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "a1",
              "name": "domain",
              "value": "={{ $json.data.domain }}",
              "type": "string"
            },
            {
              "id": "a2",
              "name": "company_name",
              "value": "={{ ($json.data.company || {}).name }}",
              "type": "string"
            },
            {
              "id": "a3",
              "name": "industry",
              "value": "={{ ($json.data.classification || {}).category }}",
              "type": "string"
            },
            {
              "id": "a4",
              "name": "description",
              "value": "={{ ($json.data.classification || {}).description }}",
              "type": "string"
            },
            {
              "id": "a5",
              "name": "logo",
              "value": "={{ (($json.data.brand || {}).logos || {}).primary ? $json.data.brand.logos.primary.url : '' }}",
              "type": "string"
            },
            {
              "id": "a6",
              "name": "brand_color",
              "value": "={{ ((($json.data.brand || {}).colors || {}).brand_colors || [])[0] ? $json.data.brand.colors.brand_colors[0].hex : '' }}",
              "type": "string"
            },
            {
              "id": "a7",
              "name": "linkedin",
              "value": "={{ (($json.data.company || {}).social_links || {}).linkedin }}",
              "type": "string"
            },
            {
              "id": "a8",
              "name": "emails",
              "value": "={{ (($json.data.company || {}).emails || []).join(', ') }}",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "id": "6d0f4c2a-1b3e-4f5a-9c7d-0e1f2a3b4c04",
      "name": "Pick fields",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [
        660,
        0
      ]
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "Domains",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Domains": {
      "main": [
        [
          {
            "node": "Prefetch enrich",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Prefetch enrich": {
      "main": [
        [
          {
            "node": "Pick fields",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "settings": {
    "executionOrder": "v1"
  },
  "pinData": {}
}
```

## Batch enrich, resumed by the batch's webhook

For hundreds of domains, one [batch](/jobs/batches) beats hundreds of calls: the workflow starts it with its own resume URL (`$execution.resumeUrl`) as the webhook, sleeps in the **Wait** node until Prefetch calls back with `batch_enrich.completed`, then reads the results and splits them into one item per domain. No polling. 12 credits per domain answered.

```json batch-enrich-with-webhook.json theme={"theme":"css-variables"}
{
  "name": "Prefetch: Batch enrich, resume on webhook",
  "nodes": [
    {
      "parameters": {},
      "id": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d01",
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [
        0,
        0
      ]
    },
    {
      "parameters": {
        "jsCode": "// Up to 500 URLs or bare domains per batch.\nconst urls = ['stripe.com', 'linear.app', 'notion.so', 'figma.com', 'vercel.com'];\nreturn [{ json: { urls } }];"
      },
      "id": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d02",
      "name": "Domains",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        220,
        0
      ]
    },
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.prefetch.io/batch/enrich",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "={{ JSON.stringify({ urls: $json.urls, webhook: { url: $execution.resumeUrl, events: ['completed', 'failed'] } }) }}",
        "options": {}
      },
      "id": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d03",
      "name": "Start batch",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        440,
        0
      ],
      "credentials": {
        "httpHeaderAuth": {
          "id": "",
          "name": "Prefetch API key"
        }
      }
    },
    {
      "parameters": {
        "resume": "webhook",
        "httpMethod": "POST",
        "limitWaitTime": true,
        "limitType": "afterTimeInterval",
        "resumeAmount": 4,
        "resumeUnit": "hours",
        "options": {}
      },
      "id": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d04",
      "name": "Wait for the batch",
      "type": "n8n-nodes-base.wait",
      "typeVersion": 1.1,
      "position": [
        660,
        0
      ],
      "webhookId": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d09"
    },
    {
      "parameters": {
        "url": "=https://api.prefetch.io/batch/enrich/{{ $('Start batch').item.json.data.id }}",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "limit",
              "value": "100"
            }
          ]
        },
        "options": {}
      },
      "id": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d05",
      "name": "Read results",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        880,
        0
      ],
      "credentials": {
        "httpHeaderAuth": {
          "id": "",
          "name": "Prefetch API key"
        }
      }
    },
    {
      "parameters": {
        "fieldToSplitOut": "data.data",
        "options": {}
      },
      "id": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d06",
      "name": "One item per URL",
      "type": "n8n-nodes-base.splitOut",
      "typeVersion": 1,
      "position": [
        1100,
        0
      ]
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "b1",
              "name": "url",
              "value": "={{ $json.url }}",
              "type": "string"
            },
            {
              "id": "b2",
              "name": "ok",
              "value": "={{ $json.ok }}",
              "type": "boolean"
            },
            {
              "id": "b3",
              "name": "error_code",
              "value": "={{ $json.error_code }}",
              "type": "string"
            },
            {
              "id": "b4",
              "name": "company_name",
              "value": "={{ ($json.company || {}).name }}",
              "type": "string"
            },
            {
              "id": "b5",
              "name": "industry",
              "value": "={{ ($json.classification || {}).category }}",
              "type": "string"
            },
            {
              "id": "b6",
              "name": "logo",
              "value": "={{ (($json.brand || {}).logos || {}).primary ? $json.brand.logos.primary.url : '' }}",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "id": "7e1a5d3b-2c4f-4a6b-8d9e-1f2a3b4c5d07",
      "name": "Pick fields",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [
        1320,
        0
      ]
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "Domains",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Domains": {
      "main": [
        [
          {
            "node": "Start batch",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Start batch": {
      "main": [
        [
          {
            "node": "Wait for the batch",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Wait for the batch": {
      "main": [
        [
          {
            "node": "Read results",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Read results": {
      "main": [
        [
          {
            "node": "One item per URL",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "One item per URL": {
      "main": [
        [
          {
            "node": "Pick fields",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "settings": {
    "executionOrder": "v1"
  },
  "pinData": {}
}
```

> [!NOTE]
>
> Prefetch only calls back to public `https://` addresses, so this works on n8n Cloud or a self-hosted n8n with a public URL, not on `localhost`. **Read results** reads up to 100 domains; for more, add pagination to it (**Options → Pagination**, mode *Response Contains Next URL*, next URL `https://api.prefetch.io{{ $response.body.data.next }}`, complete when `{{ !$response.body.data.next }}`).

## Search the web and summarize the results

Searches the web and has each of the top 5 result pages summarized in the same call, then lists title, URL and summary. 2 credits for the search plus 4 per page summarized.

```json search-and-summarize.json theme={"theme":"css-variables"}
{
  "name": "Prefetch: Search the web and summarize the results",
  "nodes": [
    {
      "parameters": {},
      "id": "8f2b6e4c-3d5a-4b7c-9e0f-2a3b4c5d6e01",
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [
        0,
        0
      ]
    },
    {
      "parameters": {
        "method": "POST",
        "url": "https://api.prefetch.io/search",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendBody": true,
        "specifyBody": "json",
        "jsonBody": "{\n  \"query\": \"open source CRM for startups\",\n  \"limit\": 5,\n  \"time_range\": \"year\",\n  \"scrape_options\": { \"formats\": [\"summary\"], \"summary_max_words\": 80 }\n}",
        "options": {
          "timeout": 60000
        }
      },
      "id": "8f2b6e4c-3d5a-4b7c-9e0f-2a3b4c5d6e02",
      "name": "Prefetch search",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        220,
        0
      ],
      "credentials": {
        "httpHeaderAuth": {
          "id": "",
          "name": "Prefetch API key"
        }
      }
    },
    {
      "parameters": {
        "fieldToSplitOut": "data.results",
        "options": {}
      },
      "id": "8f2b6e4c-3d5a-4b7c-9e0f-2a3b4c5d6e03",
      "name": "One item per result",
      "type": "n8n-nodes-base.splitOut",
      "typeVersion": 1,
      "position": [
        440,
        0
      ]
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "c1",
              "name": "title",
              "value": "={{ $json.title }}",
              "type": "string"
            },
            {
              "id": "c2",
              "name": "url",
              "value": "={{ $json.url }}",
              "type": "string"
            },
            {
              "id": "c3",
              "name": "summary",
              "value": "={{ $json.scrape ? $json.scrape.summary.text : $json.description }}",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "id": "8f2b6e4c-3d5a-4b7c-9e0f-2a3b4c5d6e04",
      "name": "Pick fields",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [
        660,
        0
      ]
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "Prefetch search",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Prefetch search": {
      "main": [
        [
          {
            "node": "One item per result",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "One item per result": {
      "main": [
        [
          {
            "node": "Pick fields",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "settings": {
    "executionOrder": "v1"
  },
  "pinData": {}
}
```

## Name the merchants on card transactions

Turns statement lines into merchants (name, website, logo, category and payment processor) and flags payments to people, transfers and fees. 3 credits per line, 1 for a line looked up in the last 7 days.

```json categorize-transactions.json theme={"theme":"css-variables"}
{
  "name": "Prefetch: Name the merchants on card transactions",
  "nodes": [
    {
      "parameters": {},
      "id": "9a3c7f5d-4e6b-4c8d-8f1a-3b4c5d6e7f01",
      "name": "Start",
      "type": "n8n-nodes-base.manualTrigger",
      "typeVersion": 1,
      "position": [
        0,
        0
      ]
    },
    {
      "parameters": {
        "jsCode": "// Replace with your transactions feed.\nreturn [\n  'SQ *BLUE BOTTLE COFFE OAKLAND CA',\n  'PAYPAL *SPOTIFYAB',\n  'AMZN Mktp US*2K4LX9B12',\n  'VENMO *JOHN SMITH',\n].map((descriptor) => ({ json: { descriptor, country: 'US' } }));"
      },
      "id": "9a3c7f5d-4e6b-4c8d-8f1a-3b4c5d6e7f02",
      "name": "Transactions",
      "type": "n8n-nodes-base.code",
      "typeVersion": 2,
      "position": [
        220,
        0
      ]
    },
    {
      "parameters": {
        "url": "https://api.prefetch.io/transaction",
        "authentication": "genericCredentialType",
        "genericAuthType": "httpHeaderAuth",
        "sendQuery": true,
        "queryParameters": {
          "parameters": [
            {
              "name": "descriptor",
              "value": "={{ $json.descriptor }}"
            },
            {
              "name": "country",
              "value": "={{ $json.country }}"
            }
          ]
        },
        "options": {
          "timeout": 30000
        }
      },
      "id": "9a3c7f5d-4e6b-4c8d-8f1a-3b4c5d6e7f03",
      "name": "Prefetch transaction",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4.2,
      "position": [
        440,
        0
      ],
      "retryOnFail": true,
      "maxTries": 3,
      "waitBetweenTries": 5000,
      "credentials": {
        "httpHeaderAuth": {
          "id": "",
          "name": "Prefetch API key"
        }
      }
    },
    {
      "parameters": {
        "assignments": {
          "assignments": [
            {
              "id": "d1",
              "name": "descriptor",
              "value": "={{ $json.data.descriptor }}",
              "type": "string"
            },
            {
              "id": "d2",
              "name": "kind",
              "value": "={{ $json.data.kind }}",
              "type": "string"
            },
            {
              "id": "d3",
              "name": "merchant",
              "value": "={{ ($json.data.merchant || {}).name }}",
              "type": "string"
            },
            {
              "id": "d4",
              "name": "website",
              "value": "={{ ($json.data.merchant || {}).domain }}",
              "type": "string"
            },
            {
              "id": "d5",
              "name": "logo",
              "value": "={{ $json.data.logo_url }}",
              "type": "string"
            },
            {
              "id": "d6",
              "name": "category",
              "value": "={{ $json.data.category }}",
              "type": "string"
            },
            {
              "id": "d7",
              "name": "processor",
              "value": "={{ $json.data.payment_processor }}",
              "type": "string"
            }
          ]
        },
        "options": {}
      },
      "id": "9a3c7f5d-4e6b-4c8d-8f1a-3b4c5d6e7f04",
      "name": "Pick fields",
      "type": "n8n-nodes-base.set",
      "typeVersion": 3.4,
      "position": [
        660,
        0
      ]
    }
  ],
  "connections": {
    "Start": {
      "main": [
        [
          {
            "node": "Transactions",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Transactions": {
      "main": [
        [
          {
            "node": "Prefetch transaction",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Prefetch transaction": {
      "main": [
        [
          {
            "node": "Pick fields",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "settings": {
    "executionOrder": "v1"
  },
  "pinData": {}
}
```

## Errors

When a request fails, the HTTP Request node's error output carries Prefetch's error body: `error_code` says what went wrong and `retryable` whether a retry can help. The templates retry automatically (**Settings → Retry On Fail**); for `retryable: false` errors such as `DNS_RESOLUTION_FAILED`, switch the node's **On Error** setting to *Continue (using error output)* and route those items aside. Failed requests are never charged.


# Integrations
Source: https://docs.prefetch.io/integrations/overview

Use Prefetch from Clay, n8n, Zapier and Make: enrich rows, name card transactions, search the web and run batches without writing code.

Prefetch is a plain HTTPS API with an `X-API-Key` header, so every no-code tool that can make an HTTP request can use it. These guides give the exact configuration for the jobs people use them for:

| You want to | Endpoint | Credits |
| - | - | - |
| Find a company's domain from its name | `GET /resolve` | 1 (3 with a live lookup) |
| Enrich a company: industry, logo, colors, emails, social profiles | `GET /enrich` | 12 |
| Just the industry, for ICP scoring | `GET /classify` | 5 |
| Show a company's logo | the [logo CDN](/company-data/logo-cdn) | 0 |
| Name the merchant on a card transaction | `GET /transaction` | 3 |
| Search the web, with each result's text | `GET /search` | 2 per 10 results |
| Enrich hundreds of domains as one job | `POST /batch/enrich` | 12 per domain |

> [card] [Clay](/integrations/clay)
>
> HTTP API columns that resolve, enrich and classify every row.

> [card] [n8n](/integrations/n8n)
>
> Four workflows to paste straight into your editor.

> [card] [Zapier](/integrations/zapier)
>
> Enrich new CRM records and name transactions with Webhooks by Zapier.

> [card] [Make](/integrations/make)
>
> Scenarios built on the HTTP "Make a request" module.

## Before you start

* **Your API key** goes in an `X-API-Key` header. Create one on the [dashboard](https://prefetch.io/dashboard). Treat it like a password: use your tool's credential store rather than pasting it into a field everyone can read.
* **Concurrency.** Every plan limits how many requests run at once: 1 on Free, 10 on Starter, 50 on Pro. Tools that run rows in parallel (Clay, n8n, Make) should stay at or under that; a request over it is refused straight away with `429` and `error_code: CONCURRENCY_LIMITED`. Failed requests cost nothing, so you can retry it.
* **Errors tell you whether to retry.** Every error body carries `error_code` and `retryable`. Retry `retryable: true` (busy, timeouts, rate limits) after a pause; don't retry `retryable: false` (an invalid domain, a site that does not exist). See [Errors](/concepts/errors).
* **Failures are free.** A request that fails is never charged, so retrying one costs nothing until it succeeds.


# Zapier
Source: https://docs.prefetch.io/integrations/zapier

Enrich new CRM companies and name the merchants on card transactions with Prefetch, using Webhooks by Zapier.

Zapier reaches Prefetch through **Webhooks by Zapier**, which can call any API. (Webhooks by Zapier is available on Zapier's paid plans.)

## Enrich new companies in your CRM

**Trigger:** your CRM's *New Company* (HubSpot, Pipedrive, Salesforce, Attio…).

**Action:** *Webhooks by Zapier → GET*

| Field | Value |
| - | - |
| URL | `https://api.prefetch.io/enrich` |
| Query String Params | `url` → the company's **domain** from the trigger |
| Headers | `X-API-Key` → your Prefetch API key |

Test the step. Zapier flattens the response, so the fields appear as, for example:

| Zapier field | What it is |
| - | - |
| `Data Company Name` | The legal or trading name |
| `Data Classification Category` | Industry (IAB) |
| `Data Classification Tagline Description` | One-line description |
| `Data Brand Logos Primary Url` | Logo image URL |
| `Data Brand Colors Brand Colors Hex` | Brand colors (the first is the main one) |
| `Data Company Social Links Linkedin` | LinkedIn page |

**Action:** your CRM's *Update Company*, mapping those fields onto your properties.

12 credits per company.

**Only have a company name?** Add a step before the enrich step: *Webhooks by Zapier → GET* `https://api.prefetch.io/resolve`, with query params `name` (the company name) and `live` (`true`). Use `Data Results Domain` from the first result. Add a *Filter by Zapier* step that continues only when `Data Results Confidence` is at least 0.8.

## Name the merchant on card transactions

**Trigger:** wherever transactions arrive: a new row in Google Sheets or Airtable, a new transaction in your banking tool.

**Action:** *Webhooks by Zapier → GET*

| Field | Value |
| - | - |
| URL | `https://api.prefetch.io/transaction` |
| Query String Params | `descriptor` → the statement line; `country` → `US` (or the card's country) |
| Headers | `X-API-Key` → your Prefetch API key |

Use `Data Kind` (`merchant`, `person`, `transfer`, `fee`, `atm` or `refund`), `Data Merchant Name`, `Data Merchant Domain`, `Data Category`, `Data Payment Processor` and `Data Logo Url`. 3 credits per transaction; 1 for a line looked up in the last 7 days.

## Long jobs: batches and webhooks

A Zap step times out long before a crawl or a large batch finishes. Split it in two:

1. **Zap 1** starts the job: *Webhooks by Zapier → Custom Request*, `POST` to `https://api.prefetch.io/batch/enrich`, with data:

   ```json theme={"theme":"css-variables"}
   {
     "urls": ["stripe.com", "linear.app", "notion.so"],
     "webhook": { "url": "YOUR_CATCH_HOOK_URL", "events": ["page"] }
   }
   ```

2. **Zap 2** receives each result: trigger *Webhooks by Zapier → Catch Hook* (its URL goes in `webhook.url` above). Every `batch_enrich.page` event carries one domain's result under `data`.

Webhooks are not available through RapidAPI keys.

## Errors

A failed step shows Prefetch's error body. `error_code` says what went wrong and `retryable` whether trying again can help: turn on Zapier's autoreplay for the retryable ones (`SERVICE_BUSY`, `CONCURRENCY_LIMITED`, `TARGET_TIMEOUT`). Failed requests are never charged.


# Batches
Source: https://docs.prefetch.io/jobs/batches

Run scrape, enrich, brand, company, classify, screenshot or styleguide on up to 500 URLs as one job. Free to submit; each URL costs what one call costs.

A batch runs one endpoint over a list of URLs, up to 500, as a single background job. You send one request instead of hundreds, and Prefetch manages concurrency for you.

| Path | Each URL is answered as | Credits per URL |
| - | - | - |
| `POST /batch/scrape` | [`/scrape`](/web-data/scrape), configured with `scrape_options` | 1, or 4 with `summary`, `json` or `check_prompt_injection` |
| `POST /batch/enrich` | [`/enrich`](/company-data/enrich) | 12 |
| `POST /batch/brand` | [`/brand`](/company-data/brand) | 10 |
| `POST /batch/styleguide` | [`/styleguide`](/company-data/styleguide) | 10 |
| `POST /batch/company` | [`/company`](/company-data/company) | 5 |
| `POST /batch/classify` | [`/classify`](/company-data/classify) | 5 |
| `POST /batch/screenshot` | [`/screenshot`](/web-data/screenshot) | 1 |

Each URL is answered exactly as a single call would answer it: curated data first, then a live read. A batch scrape fetches only the URLs you list. It follows no links and reads no sitemap. To discover pages, use a [crawl](/web-data/crawl).

## Example requests

```bash Enrich a list of domains theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/batch/enrich" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["stripe.com", "linear.app", "notion.so"],
    "webhook": "https://example.com/hooks/prefetch"
  }'
```

```bash Scrape a list of pages theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/batch/scrape" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://stripe.com/pricing", "https://stripe.com/docs"],
    "scrape_options": { "formats": ["markdown"], "only_main_content": true }
  }'
```

```bash Brand kits with design tokens theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/batch/brand" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://vercel.com", "https://figma.com"],
    "options": { "design_tokens": true },
    "concurrency": 3
  }'
```

```javascript Node.js (submit and poll) theme={"theme":"css-variables"}
const base = "https://api.prefetch.io";
const headers = { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" };

const submit = await fetch(`${base}/batch/enrich`, {
  method: "POST",
  headers,
  body: JSON.stringify({ urls: ["stripe.com", "linear.app", "notion.so"] }),
});
const { data: job } = await submit.json();

let status;
do {
  await new Promise((r) => setTimeout(r, 5000));
  ({ data: status } = await (await fetch(`${base}/batch/enrich/${job.id}`, { headers })).json());
} while (status.status === "pending" || status.status === "running");

for (const item of status.data) {
  console.log(item.url, item.ok ? item.company?.name : item.error_code);
}
```

```python Python (submit and poll) theme={"theme":"css-variables"}
import os, time, requests

base = "https://api.prefetch.io"
headers = {"X-API-Key": os.environ["PREFETCH_API_KEY"]}

job = requests.post(
    f"{base}/batch/enrich",
    headers=headers,
    json={"urls": ["stripe.com", "linear.app", "notion.so"]},
).json()["data"]

while True:
    time.sleep(5)
    status = requests.get(f"{base}/batch/enrich/{job['id']}", headers=headers).json()["data"]
    if status["status"] not in ("pending", "running"):
        break

for item in status["data"]:
    print(item["url"], item["company"]["name"] if item["ok"] else item["error_code"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "crw_7c2e9a4b1d0f4e6a8b3c5d7e9f1a2b3c",
    "status": "pending",
    "endpoint": "enrich",
    "url_count": 3,
    "invalid_urls": [],
    "created_at": "2026-10-13T09:14:03.221Z",
    "expires_at": "2026-10-14T09:14:03.221Z"
  },
  "meta": { "requestId": "1d2c3b4a-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "durationMs": 212 }
}
```

Batch ids start with `crw_`, like crawl ids, because batches run on the same job system. Read results with `GET /batch/{endpoint}/{id}`, for example `GET /batch/enrich/crw_7c2e…`. See [Async jobs](/concepts/async-jobs) for polling, pagination and expiry.

## Results

Each result carries every field the single endpoint returns for that URL (`domain`, `brand`, `company`, `classification`, `screenshot_url`, `styleguide`, `markdown`…), plus:

| Field | Meaning |
| - | - |
| `ok` | `false` when the URL couldn't be answered. You aren't charged for it. |
| `error`, `error_code` | Why, as one of the API's [error codes](/concepts/errors). |
| `status_code` | `200` for an answered URL. |

`GET /batch/{endpoint}/{id}/errors` lists only the URLs that failed, so you can resubmit the retryable ones.

## Options

### Endpoint options

For `/batch/{endpoint}`, `options` are that endpoint's own parameters, applied to every URL. Both snake\_case and camelCase work, as typed JSON or as strings:

| Endpoint | Example `options` |
| - | - |
| brand, enrich | `{ "design_tokens": true, "css": true, "screenshot_colors": 5 }` |
| screenshot | `{ "device": "iphone_15", "dark_mode": true, "format": "webp" }` |
| styleguide | `{ "dark_mode": true }` |
| company, classify | none |

For `/batch/scrape`, use `scrape_options` instead. It takes everything [`/scrape`](/web-data/scrape) takes.

Options are checked before anything is queued. An invalid option is a `400` that names it.

### Job options

| Option | Default | Meaning |
| - | - | - |
| `concurrency` | 2 | URLs run in parallel, 1 to 5. Brand, enrich, screenshot and styleguide batches render every page, so they run at most 3 at a time and default to 3. |
| `ignore_invalid_urls` | `false` | Drop malformed or blocklisted URLs, listed in `invalid_urls`, instead of rejecting the whole batch with a `400`. |
| `webhook` | none | Get each result pushed to you. See below. |

Duplicates, including the same site under another spelling (`www.`, a trailing slash), run once.

## Webhooks

`webhook` works as it does for [crawls](/web-data/crawl#webhooks). Events are named for the endpoint: `batch_enrich.started`, `batch_enrich.page` (one per URL, carrying its result), `batch_enrich.completed` and `batch_enrich.failed`, or `batch_scrape.*` for a batch scrape. Each delivery is signed with the secret returned when the batch is created. See [Webhooks](/concepts/webhooks).

Webhooks aren't available through RapidAPI. Poll the status endpoint instead.

## Credits

Submitting is free. Each URL answered costs what one call of that endpoint costs, charged as URLs complete, and never twice. Failed URLs are free.

A `/batch/{endpoint}` job your key can't pay for in full is refused up front with `CREDITS_EXHAUSTED`, and the message says how many URLs fit. A 500-domain `/batch/enrich` can cost up to 6,000 credits.

## Over MCP

`prefetch_batch` and `prefetch_batch_scrape` submit a batch and wait for it, returning the results if it finishes in time and an id for `prefetch_check_crawl_status` if not.

## Next

> [card] [Build a company directory](/recipes/company-directory)
>
> A recipe that enriches hundreds of domains with one batch.

> [card] [API reference](/api-reference/endpoint/batch)
>
> Every parameter, and a playground to try it.


# MCP server
Source: https://docs.prefetch.io/mcp/overview

Connect Claude, ChatGPT, Cursor or any MCP client to Prefetch, so your agent can scrape, crawl, enrich and monitor on its own.

Prefetch speaks the [Model Context Protocol](https://modelcontextprotocol.io), so an AI agent can call the API directly instead of you writing HTTP glue for it.

There's nothing to install. The MCP server *is* the API, at one endpoint:

```
https://api.prefetch.io/mcp
```

Apps sign you in with your Prefetch account, so there's no key to copy. Clients you configure yourself can use your API key instead.

## Connect

> [tab] Claude
>
> Prefetch is in the Claude directory. It works on claude.ai, Claude Desktop and Claude mobile.
>
> 1. Open [Prefetch in the Claude directory](https://claude.ai/directory/prefetch) and select **Connect**.
> 2. Sign in to Prefetch and select **Allow access**.
>
> On Team and Enterprise plans, an Owner first adds Prefetch under **Organization settings → Connectors**. Members then connect with their own Prefetch account.

> [tab] ChatGPT
>
> 1. Open [chatgpt.com/plugins](https://chatgpt.com/plugins), select **+**, then **Add custom MCP server**.
> 2. Enter a name, paste `https://api.prefetch.io/mcp`, and choose **OAuth** for authentication.
> 3. Create it, sign in to Prefetch, and select **Allow access**.

> [tab] Claude Code
>
> If you sign in to Claude Code with your Claude account, connectors you add on claude.ai come with it. Once you've connected Prefetch from the [Claude directory](https://claude.ai/directory/prefetch), it's already listed under `/mcp`.
>
> Otherwise, add the server directly:
>
> ```bash theme={"theme":"css-variables"}
> claude mcp add --transport http prefetch https://api.prefetch.io/mcp
> ```
>
> Then run `/mcp`, choose **prefetch**, and select **Authenticate** to sign in from your browser.
>
> To use an API key instead, for CI or a machine without a browser:
>
> ```bash theme={"theme":"css-variables"}
> claude mcp add --transport http prefetch https://api.prefetch.io/mcp \
>   --header "X-API-Key: $PREFETCH_API_KEY"
> ```

> [tab] Cursor
>
> Add this to `.cursor/mcp.json` in your project, or to `~/.cursor/mcp.json` for every project:
>
> ```json theme={"theme":"css-variables"}
> {
>   "mcpServers": {
>     "prefetch": {
>       "url": "https://api.prefetch.io/mcp"
>     }
>   }
> }
> ```
>
> Cursor opens the Prefetch sign-in when it first connects. To use an API key instead, add `"headers": { "X-API-Key": "your_api_key_here" }`.

> [tab] Other clients
>
> Any client that supports remote MCP servers over streamable HTTP works. Point it at:
>
> ```
> https://api.prefetch.io/mcp
> ```
>
> Clients that support MCP authorization sign you in on their own. Otherwise, send your key as an `X-API-Key` or an `Authorization: Bearer` header.

When you sign in, the consent screen shows which app is asking and where it will send you back. A connected app's calls use your account's credits, exactly like API requests. You can see and disconnect your apps under **Connected Apps** on the [dashboard](https://prefetch.io/dashboard). A disconnected app loses access on its next call.

> [!WARNING]
>
> If you use an API key, keep it in your client's secret storage or an environment variable, never in the URL. URLs end up in logs, shell history and shared config files.

## Try it

Once you're connected, ask for what you want in plain language:

> Get me the brand colors and industry category for stripe.com

> Find every pricing page on vercel.com and summarize what changed

> Crawl the /docs section of fastapi.tiangolo.com and list the endpoints it documents

> Watch linear.app/pricing every morning and tell me when a plan's price changes

Your agent picks the right tool, calls it, and reads the result.

## The tools

| Tool | What it does | Credits |
| - | - | - |
| `prefetch_resolve` | A company, brand or product name → its domain | 1, or 3 with a live lookup |
| `prefetch_transaction` | A card transaction line → its merchant | 3, or 1 for a repeat |
| `prefetch_search` | Web search results, optionally with each page's content | 2 per 10 results, + each page scraped |
| `prefetch_scrape` | One page as markdown, summary, HTML, links, images or JSON | 1, or 4 with summary or JSON |
| `prefetch_map` | Every URL a site exposes, without fetching the pages | 1 |
| `prefetch_crawl` | Many pages of a site as markdown | 1 per page |
| `prefetch_batch_scrape` | A list of known URLs as markdown | 1 per page |
| `prefetch_batch` | Brand, enrich, company, classify, screenshot or styleguide on many URLs | Each URL's price |
| `prefetch_check_crawl_status` | Status and results for a crawl or batch | Free |
| `prefetch_cancel_crawl` | Stop a crawl early | Free |
| `prefetch_enrich` | Brand, company and classification in one call | 12 |
| `prefetch_brand` | Colors, fonts, logos, favicon and Open Graph images | 10 |
| `prefetch_company` | Name, emails, addresses and social profiles | 5 |
| `prefetch_classify` | IAB category, description and stock tickers | 5 |
| `prefetch_styleguide` | A site's design system, with CSS and Tailwind exports | 10 |
| `prefetch_screenshot` | Render a page and return a hosted image URL | 1 |
| `prefetch_logo_urls` | Embeddable logo URLs for up to 50 domains | Free, from your logo quota |
| `prefetch_answer` | A researched, sourced answer in the JSON shape you give | 10, or 100 in `ultra` mode |
| `prefetch_create_monitor` | Watch pages on a schedule, optionally against a goal | Free. Each check is billed. |
| `prefetch_run_monitor` | Run a monitor's check now and see what changed | 1 per page, +3 per JSON extraction, +1 per change judged |
| `prefetch_get_monitor_check` | What a monitor's check found | Free |
| `prefetch_list_monitors`, `prefetch_get_monitor` | Your monitors and their recent checks | Free |
| `prefetch_update_monitor`, `prefetch_delete_monitor` | Change, pause, resume or delete a monitor | Free |

See the [tool reference](/mcp/tools) for every parameter. Credits work exactly as they do over REST: same prices, and only successful calls are charged. See [Credits](/concepts/credits).

## How crawling works

A crawl takes minutes, which is longer than an agent wants to wait on a tool call. So `prefetch_crawl` starts the crawl and waits for it, up to `wait_seconds` (60 by default).

If the crawl finishes in time, you get the pages straight away. If not, you get the crawl id and an instruction:

```
Crawl crw_a1b2c3 is still running: 12 of 25 pages done.

Call prefetch_check_crawl_status with id="crw_a1b2c3" to collect the results.
Call prefetch_cancel_crawl with the same id to stop it early.
```

* **Polling is free.** Pages are billed as they complete, so checking twice never charges twice.
* **Disconnecting cancels the crawl.** If your client hangs up while `prefetch_crawl` is still waiting, the crawl stops rather than running on and billing pages nobody will read.

`prefetch_batch` and `prefetch_batch_scrape` wait the same way.

## How monitors work

A monitor keeps checking after the conversation ends, so its results have to be read back. `prefetch_run_monitor` runs a check and waits for it, and `prefetch_get_monitor_check` shows the latest check at any time. Both answer with what changed, not with every page:

```
Check chk_8e2d… completed (manual). 12 pages: 1 changed, 11 unchanged. Credits charged: 37.

## CHANGED: Pricing (https://example.com/pricing)
Judge: MEANINGFUL (high confidence). The Starter plan went from $19 to $24 a month.
- plans[0].price: "$19/mo" → "$24/mo"
```

The first check records a baseline, so changes show from the second check on. `run_now: true` on `prefetch_create_monitor` takes that first check straight away. Every check is billed for as long as the monitor is active, and the create tool tells the agent so. Pause or delete monitors you no longer need.

## Response size

Tool results go straight into your agent's context window, so content is capped at **50,000 characters** per result, well below the REST API's 1 MB cap. A full Wikipedia article in `raw_html` is about 240,000 characters, and one uncapped call like that would crowd out most of what the agent knows.

Truncation is always announced:

```
---
[truncated: 189,747 of 239,747 characters omitted.
 Narrow the extraction with include_selectors, or keep only_main_content=true.]
```

To fit more signal into less space:

> [card] Target the content
>
> Pass `include_selectors` with the part of the page you want, like `["article"]`.

> [card] Ask for a summary
>
> Use `formats: ["summary"]` instead of `["markdown"]` when you only need the gist.

## Errors

Failures come back as readable tool results rather than transport errors, so your agent can read the message and correct itself:

```
formats: unsupported value(s) pdf. Supported: markdown, summary, html, raw_html, links, images, json (HTTP 400)
The target URL could not be resolved. Please check the domain name. (HTTP 422)
Private or reserved IP ranges are not allowed (HTTP 400)
```

Authentication is the exception, and fails at the HTTP layer. A `401` means no credentials, or an access token that expired or was disconnected, and apps react by refreshing the token or asking you to sign in again. A `403` means an invalid key or an account out of credits, which signing in again won't fix. See [Authentication](/concepts/authentication) and [Error handling](/concepts/errors).

## Good to know

> [accordion] What a connected app can do
>
> A connected app can call every tool on this page as you, and its calls use your credits. It can't see your password, payment details or API keys, and it can't change your plan.
>
> Each tool tells the app whether it only reads or changes something. Claude runs the read-only tools (scraping, mapping, brand and company lookups, reading monitors) without asking, and asks before anything that starts a crawl or creates, changes, runs or deletes a monitor.

> [accordion] MCP and REST are the same API
>
> Both run the same pipeline, so credits, caching, rate limits and the blocklist behave the same either way. An MCP scrape can even be answered from the cache a REST scrape filled, because both build the same cache key.

> [accordion] The endpoint is stateless
>
> Every request stands alone, so there are no MCP sessions to manage. Every tool is one request and one response. Long-running work like crawls and monitor checks is stored on our side and read back by id, so nothing is lost. `GET` and `DELETE` on `/mcp` return `405`. Use `POST`.

> [accordion] RapidAPI subscriptions can't use MCP
>
> RapidAPI meters usage from a response header that has to be set before the response body is written, and over MCP the cost of a call isn't known until the tool has run. Rather than under-bill silently, `/mcp` returns `400` for RapidAPI traffic.
>
> Everything is available over REST through RapidAPI as documented. MCP needs a Prefetch account: sign in when your app asks, or use a key from the [dashboard](https://prefetch.io/dashboard).

> [accordion] Which tool should my agent use?
>
> Each tool's description tells the agent when to use it and when to use something else, so this mostly takes care of itself. Two patterns help:
>
> * **`prefetch_enrich` beats three separate calls.** It's one page fetch instead of three, and costs less than `prefetch_brand`, `prefetch_company` and `prefetch_classify` together.
> * **Map, then scrape, usually beats crawling.** `prefetch_map` is cheap and tells you which pages exist. Scraping the three you want costs far less than crawling fifty.

## Next steps

> [card] [Tool reference](/mcp/tools)
>
> Every tool, every parameter.

> [card] [Agent quickstart](/agent-quickstart)
>
> One prompt that sets Prefetch up in your project.

> [card] [Authentication](/concepts/authentication)
>
> Keys, OAuth and error codes.

> [card] [REST API](/api-reference/introduction)
>
> The same capabilities over HTTP.


# MCP tools
Source: https://docs.prefetch.io/mcp/tools

Every tool the Prefetch MCP server exposes, with its parameters and defaults.

Twenty-five tools: one per API capability, plus the extra verbs crawls, batches and monitors need. Your agent reads these descriptions and picks the right one, so you rarely need to name a tool yourself.

All parameters are snake\_case. Most tools require only `url`. The exceptions: `name` for `prefetch_resolve`, `descriptor` for `prefetch_transaction`, `query` for `prefetch_search`, `task` for `prefetch_answer`, `urls` for the batch tools, `domains` for `prefetch_logo_urls`, `id` for the crawl and monitor tools that act on one, and `name` plus `schedule` to create a monitor.

See [MCP server](/mcp/overview) for setup.

## Finding a domain

### `prefetch_resolve`

Turns a company, brand or product name into the domain of its official website: "Stripe" → `stripe.com`. Every other tool takes a URL, so this is where a task that starts from a name begins: resolve the name, then call `prefetch_enrich`, `prefetch_brand` or `prefetch_company` with the domain.

Each result has a `confidence` from 0 to 1. Only the first can reach 0.8, and at or above it that result is the answer. Over MCP, names the index is unsure of are looked up live by default. That takes a few seconds and costs 3 credits, versus 1 from the index.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | string | none | **Required.** The name, like `"Delta Air Lines"` or `"Figma"`. 1–100 characters. |
| `limit` | number | `5` | How many candidates to return. 1–10. |
| `live` | boolean | `true` | Look the name up live when the index is unsure. `false` for an instant, index-only lookup (free when nothing matches). |

### `prefetch_transaction`

Turns a card transaction descriptor (a bank statement line like `SQ *BLUE BOTTLE COFFE OAKLAND CA`) into the merchant behind it: its name, website, processor and location, and a `logo_url` ready to show. Lines that are payments to a person, transfers, fees or ATM withdrawals say so in `kind`. See [`GET /transaction`](/company-data/transaction).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `descriptor` | string | none | **Required.** The statement line. Up to 200 characters. |
| `country` | string | none | Two-letter code of the country the card was used in. |
| `mcc` | string | none | The four-digit merchant category code, if known. |
| `include_brand` | boolean | `false` | Also return the merchant's logos and colors, as `prefetch_brand` does. +10 credits. |

3 credits per lookup, 1 for a line looked up in the last 7 days.

## Web extraction

### `prefetch_search`

Search the web (Google results) and get each result's title, URL and snippet, optionally with every result page scraped into markdown in the same call. Use it to find pages. For a researched answer, use `prefetch_answer`. See [`GET /search`](/web-data/search).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `query` | string | none | **Required.** What to search for. Search operators work: `"exact phrase"`, `-word`, `filetype:pdf`. |
| `limit` | number | `10` | Results to return. 1–50, or 1–10 with `scrape_results`. |
| `type` | string | `web` | `web` or `news`. |
| `time_range` | string | none | `hour`, `day`, `week`, `month` or `year`. |
| `country`, `language` | string | none | Two-letter codes. |
| `include_domains`, `exclude_domains` | string\[] | none | Up to 10 each. |
| `scrape_results` | boolean | `false` | Also fetch each result page. 1 credit per page, 4 with `summary` or `json`. |
| `formats` | string\[] | `["markdown"]` | With `scrape_results`: the page formats. |

2 credits per 10 results, plus 1 per page scraped (4 with `summary` or `json`).

### `prefetch_scrape`

Fetch one URL and return its content. Handles JavaScript-rendered pages, strips boilerplate, and resolves every link and image to an absolute URL.

Use it when you know which page you want. To find pages first, use `prefetch_map`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** `https://` is assumed if the scheme is omitted. |
| `formats` | string\[] | `["markdown"]` | Any of `markdown`, `summary`, `html`, `raw_html`, `links`, `images`, `json`, `screenshot`. |
| `only_main_content` | boolean | `true` | Strip navigation, sidebars, headers, and footers. |
| `include_links` | boolean | `true` | Keep hyperlinks in the markdown. |
| `include_images` | boolean | `true` | Keep images in the markdown. |
| `include_base64_images` | boolean | `false` | Keep inline `data:` image URIs. These are very large. |
| `include_selectors` | string\[] | none | CSS selectors to keep, overriding main-content detection. |
| `exclude_selectors` | string\[] | none | CSS selectors to drop, like `[".cookie-bar", "#promo"]`. |
| `json_prompt` | string | none | For `formats: ["json"]`: what to extract, in plain English. |
| `json_schema` | object | none | For `formats: ["json"]`: a JSON Schema the result must match. |
| `summary_max_words` | number | `120` | Word budget for `formats: ["summary"]`. 20–400. |
| `screenshot_full_page` | boolean | `false` | For `formats: ["screenshot"]`: capture the whole page rather than the first screen. |
| `wait_for` | number | none | Milliseconds to wait after load for late content (up to 30,000). |
| `wait_for_selector` | string | none | Wait up to 10 seconds for this CSS selector before reading. Best effort. |
| `mobile` | boolean | `false` | Render the page as a phone. |
| `max_age` | number | none | Accept a stored copy fetched at most this many milliseconds ago. Default: always fetch live. |
| `headers` | object | none | Request headers to send to the site, like `{"Accept-Language": "de-DE"}`. Requests with headers are never cached. |
| `check_prompt_injection` | boolean | `false` | Check the page for text aimed at AI models and put the verdict above the page. Adds the 3-credit AI surcharge. |

> [!TIP]
>
> `include_selectors` is the best way to cut a large page down to what matters. It beats truncation, because you choose what survives.

`raw_html` is much larger than `markdown`. Only ask for it when you need the source.

### `prefetch_map`

Discover the URLs on a site, from its sitemaps and on-page links, without fetching page content. Fast and cheap.

Mapping first and then scraping the two or three pages you want is usually better, and much cheaper, than crawling.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** |
| `search` | string | none | Rank and filter results by this term, like `"pricing"`. |
| `limit` | number | `1000` | Maximum URLs to return. 1–5000. |
| `sitemap` | string | `include` | `include` merges sitemap and link discovery, `only` trusts the sitemap alone, `skip` ignores it. |
| `include_subdomains` | boolean | `true` | Include URLs on subdomains. |
| `ignore_query_params` | boolean | `true` | Collapse URLs that differ only by query string. |

### `prefetch_crawl`

Crawl a site or a section of one, returning each page as markdown. Starts the crawl and waits for it. See [how crawling works](/mcp/overview#how-crawling-works).

Crawls are billed per page. Scope them with `include_paths` and keep `limit` as low as will do.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** |
| `limit` | number | `25` | Maximum pages to crawl. 1–500. Each page is billed. |
| `max_depth` | number | `2` | How many links deep to follow. 0–5. |
| `include_paths` | string\[] | none | Regex patterns; a URL must match at least one, like `["^/docs/"]`. |
| `exclude_paths` | string\[] | none | Regex patterns; a URL matching any is skipped. |
| `allow_subdomains` | boolean | `false` | Follow links onto subdomains. |
| `allow_external_links` | boolean | `false` | Follow links onto other sites. This can make a crawl very large. |
| `ignore_query_params` | boolean | `true` | Treat URLs differing only by query string as one page. |
| `use_sitemap` | boolean | `true` | Seed the crawl from the site's sitemap as well as from links. |
| `concurrency` | number | `2` | Pages fetched in parallel. 1–5. |
| `delay_ms` | number | `0` | Politeness delay between pages. |
| `scrape_options` | object | none | How each page is rendered: the same options `prefetch_scrape` takes. |
| `wait_seconds` | number | `60` | How long to wait before handing back a crawl id to poll. 0–120. |

> [!NOTE]
>
> Sitemap-seeded pages sit at depth 0, because they were handed over rather than followed. So `max_depth: 0` with `use_sitemap: true` crawls exactly what the sitemap lists and follows nothing.

### `prefetch_check_crawl_status`

Status and results for a crawl or batch. Returns one page of results at a time.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | string | none | **Required.** The id from `prefetch_crawl`, `prefetch_batch_scrape` or `prefetch_batch`. |
| `skip` | number | `0` | Results to skip, for paging. |
| `limit` | number | `25` | Results per page. 1–100. |

Calling this is free. Only pages that completed since your last call are billed.

### `prefetch_cancel_crawl`

Stop a running crawl. Pages already fetched stay readable via `prefetch_check_crawl_status` until the crawl expires.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | string | none | **Required.** The crawl id from `prefetch_crawl`. |

### `prefetch_batch_scrape`

Scrape many known URLs in one job and get each page as markdown. Starts the job and waits for it (`wait_seconds`, default 60), returning the pages if it finishes in time and an id for `prefetch_check_crawl_status` if not. See [`POST /batch/scrape`](/jobs/batches).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `urls` | string\[] | none | **Required.** 1–500 pages. |
| `scrape_options` | object | none | How each page is rendered: the options `prefetch_scrape` takes. |
| `concurrency` | number | `2` | Pages fetched in parallel. 1–5. |
| `ignore_invalid_urls` | boolean | `false` | Drop invalid URLs instead of failing the batch. |

1 credit per page returned.

### `prefetch_batch`

Run `brand`, `enrich`, `company`, `classify`, `screenshot` or `styleguide` on a list of URLs or bare domains as one job, and get every result back: the same result each single tool returns. Waits like `prefetch_batch_scrape`. See [`POST /batch/{endpoint}`](/jobs/batches).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `endpoint` | string | none | **Required.** Which tool to run on every URL. |
| `urls` | string\[] | none | **Required.** 1–500 URLs or domains, like `["stripe.com", "linear.app"]`. |
| `options` | object | none | That tool's own options, applied to every URL: `{"design_tokens": true}` for brand, `{"device": "iphone_15"}` for screenshot. |
| `concurrency` | number | `2` | URLs run in parallel. 1–5. |
| `ignore_invalid_urls` | boolean | `false` | Drop invalid URLs instead of failing the batch. |

Each URL costs what one call of that tool costs; failed URLs are free.

## Brand and company data

### `prefetch_enrich`

Everything known about the company behind a URL in one call: brand assets, company details, and IAB classification.

> [!TIP]
>
> Prefer this over calling `prefetch_brand`, `prefetch_company`, and `prefetch_classify` separately. It is one page fetch instead of three, and costs less than the three combined.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** |
| `html` | boolean | `false` | Also extract colors from inline HTML style attributes. |
| `css` | boolean | `false` | Also extract colors from stylesheets, grouped by CSS property. |
| `javascript` | boolean | `false` | Also extract colors from inline JavaScript. |
| `screenshot_colors` | number | none | Sample this many dominant colors from a rendered screenshot. 2–12. |
| `screenshot_width` | number | `1440` | Screenshot viewport width. |
| `screenshot_height` | number | `900` | Screenshot viewport height. |
| `screenshot_full_page` | boolean | `false` | Capture the whole scrollable page. |
| `filter_achromatic` | boolean | `false` | Drop near-white, near-black, and grey results. |
| `design_tokens` | boolean | `false` | Also return `brand.design_tokens`: colors by role, heading and body type, and button and input styles. |

`screenshot_colors` catches colors that only exist inside images, at the cost of a slower call. `design_tokens` is what to ask for when building UI that should match the site.

### `prefetch_brand`

Brand identity for a URL: palette with color names and hex values, font families, logos, favicon, and Open Graph images.

Takes the same parameters as `prefetch_enrich`. Use `prefetch_enrich` instead if you also want company details or industry.

### `prefetch_company`

Company name, contact emails, postal addresses, and social profiles for the organization behind a URL.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** |

### `prefetch_classify`

IAB content category and subcategory, with a description and, for public companies, stock tickers and ISINs.

The cheapest way to answer "what kind of business is this".

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** |

### `prefetch_screenshot`

Render a page and return a hosted image URL.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** |
| `width` | number | `1440` | Viewport width. 320–2560. Ignored with `device`. |
| `height` | number | `900` | Viewport height. 240–5000. Ignored with `device`. |
| `format` | string | `jpeg` | `jpeg`, `png`, `webp`, or `pdf`. |
| `full_page` | boolean | `false` | Capture the whole scrollable page. |
| `device` | string | none | Render as a phone, tablet or retina desktop: `iphone_15`, `pixel_7`, `ipad`, `desktop_retina`… (see [`/screenshot`](/web-data/screenshot#devices)). |
| `dark_mode` | boolean | `false` | Ask the page for its dark theme. |
| `selector` | string | none | Capture only the first element matching this CSS selector. |
| `wait_for` | number | `0` | Milliseconds to wait after load. Up to 30,000. |
| `wait_for_selector` | string | none | Wait (up to 10 s) for this CSS selector before capturing. |
| `block_ads` | boolean | `false` | Block ad and tracker requests while the page loads. |
| `quality` | number | `85` | JPEG and WebP quality. 1–100. |

> [!NOTE]
>
> This returns a link, not image bytes. Pass the URL on to the user, or to a tool that can fetch images.

### `prefetch_styleguide`

A site's design system, read from the rendered page: colors by role, the type scale, spacing, radii, shadows, button, input, card and link styles, breakpoints and the site's own CSS variables, plus the same as CSS custom properties (`exports.css`) and a Tailwind theme (`exports.tailwind`). Use it to build UI that matches a site. See [`GET /styleguide`](/company-data/styleguide).

| Parameter | Type | Default | Description |
| - | - | - | - |
| `url` | string | none | **Required.** |
| `dark_mode` | boolean | `false` | Read the site's dark theme instead of its default one. |

10 credits.

### `prefetch_logo_urls`

Ready-to-embed logo image URLs for up to 50 domains, from the [logo CDN](/company-data/logo-cdn). Put them straight in `<img>` tags or markdown. A domain without a known logo shows a letter mark.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `domains` | string\[] | none | **Required.** 1–50 domains or URLs. |
| `size` | number | `128` | Pixels, square. 16–512. |
| `format` | string | `png` | `png`, `webp` or `jpeg`. |

Free: logos use your plan's monthly logo quota, not credits.

## Research

### `prefetch_answer`

Research a question on the live web and get a sourced answer as JSON in the shape you describe. It searches the web, reads pages, and looks up company records as the task needs, then returns `json_content` in the shape of `json_format` plus the `sources` it read. Facts it could not establish come back `null`.

Use it when the answer needs searching or several sources. When you already know the page, `prefetch_scrape` with `formats: ["json"]` is cheaper; for a company's profile from its URL, use `prefetch_enrich`.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `task` | string | none | **Required.** The research question. Name a domain or URL to focus it: named pages are read first. Up to 2,000 characters. |
| `mode` | string | `fast` | `fast`: up to 30 s, 10 credits. `ultra`: deeper research across several sources, up to 50 s, 100 credits. |
| `json_format` | object | `{"result": ""}` | An example of the answer object, not a JSON Schema, like `{"ceo": "", "founded_year": 0}`. Keys and value types are kept; unknowns come back `null`. |
| `timeout_opts` | object | none | `{ milliseconds, behavior }`. Shortens the mode's deadline (1,000–300,000 ms). With `behavior: "return-partial"`, what was found so far is returned with `partial: true`. |
| `tags` | string\[] | none | Labels stored on the request log, for filtering usage. Up to 20. |

> [!NOTE]
>
> Over MCP the default mode is `fast`; over REST it is `ultra`. Failures and timeouts are never charged.

## Monitoring

A monitor re-checks pages on a schedule and records what changed. See [Monitors](/monitors/overview) for how changes are detected and judged. The tools take a flatter shape than the REST body: `urls` for specific pages and `crawl_url` for a site, instead of a list of targets.

An agent rarely has a webhook to receive changes at, so it reads them back, or passes `email` to have each check that finds changes emailed to a person: `prefetch_run_monitor` runs a check and waits for it, and `prefetch_get_monitor_check` shows the latest check by default. Both list only the pages that changed, appeared, disappeared or failed, the judge's verdict first, then any field changes, then the diff, and count the unchanged ones.

### `prefetch_create_monitor`

Start watching pages. Pass `urls`, `crawl_url`, or both.

A monitor bills on every check for as long as it's active: 1 credit per page fetched, +3 when a JSON extraction runs, and +1 per change judged. So prefer few pages and a modest schedule.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `name` | string | none | **Required.** A label, like `"Acme pricing"`. |
| `schedule` | string | none | **Required.** A phrase: `"every 30 minutes"`, `"hourly"`, `"daily at 9am"`, `"every weekday at 17:00"`, `"weekly"`, or five-field cron. As often as the plan allows: hourly on Free, every 5 minutes on Starter and Pro, 2 on Growth, 1 on Scale. |
| `timezone` | string | `UTC` | IANA timezone for the schedule, like `"America/New_York"`. |
| `goal` | string | none | What you want to be told about, in one sentence. Each change is judged against it, so noise is filtered out. |
| `urls` | string\[] | none | Pages to watch. 1–100. |
| `crawl_url` | string | none | A site or section to re-crawl on every check, so new and removed pages are reported too. |
| `crawl_limit` | number | `25` | Most pages each crawl visits. 1–500. Every page is billed on every check. |
| `include_paths` | string\[] | none | For `crawl_url`: regex patterns a page must match, like `["^/blog/"]`. |
| `exclude_paths` | string\[] | none | For `crawl_url`: regex patterns to skip. |
| `track_fields` | string | none | Compare these facts instead of the page text, like `"each plan's monthly price"`. A page then counts as changed only when one of them changes. |
| `include_selectors` | string\[] | none | CSS selectors to compare instead of the whole main content. |
| `exclude_selectors` | string\[] | none | CSS selectors to ignore: timestamps, rotating banners. |
| `webhook_url` | string | none | An HTTPS endpoint to POST changes to. |
| `email` | string\[] | none | Up to 5 addresses to email when a check finds changes. Your account's own address works at once; any other address confirms from an email first. |
| `run_now` | boolean | `false` | Take the first check immediately. It records a baseline (every page is new), so changes show from the second check on. |

### `prefetch_run_monitor`

Run a check now, wait for it, and return what changed since the previous check. Billed like any check.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | string | none | **Required.** The monitor id. |
| `wait_seconds` | number | `60` | How long to wait before handing back the check id to read later. 0–120. |

### `prefetch_get_monitor_check`

What a check found. Leave `check_id` out for the most recent one. Free.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `monitor_id` | string | none | **Required.** |
| `check_id` | string | latest | A check id. |
| `status` | string | none | Only pages with this status: `same`, `new`, `changed`, `removed` or `error`. Without it, unchanged pages are counted but not listed. |
| `skip` | number | `0` | Pages to skip, for paging. |
| `limit` | number | `25` | Pages per response. 1–100. |

### `prefetch_list_monitors`

The key's monitors with each one's schedule and last check. Free.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `limit` | number | `25` | Monitors per page. 1–100. |
| `offset` | number | `0` | Monitors to skip. |

### `prefetch_get_monitor`

One monitor's settings, next run, estimated cost, and its five most recent checks. Free.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | string | none | **Required.** |

### `prefetch_update_monitor`

Change a monitor. Fields you leave out stay as they are. Free.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | string | none | **Required.** |
| `name` | string | none | A new label. |
| `schedule`, `timezone` | string | none | A new schedule. Pass `timezone` together with `schedule`. |
| `goal` | string \| null | none | A new goal, or `null` to stop judging and report every change. |
| `status` | string | none | `paused` stops the schedule and its charges; `active` resumes it. |
| `urls`, `crawl_url`, … | | none | Replace what the monitor watches. Takes the same fields as `prefetch_create_monitor`. |
| `webhook_url` | string \| null | none | A new webhook URL, or `null` to stop sending webhooks. |
| `email` | string\[] \| null | none | The full new list of addresses to email, replacing the old one. `null` or `[]` stops emailing. |

### `prefetch_delete_monitor`

Delete a monitor and its history, stopping all future checks. To stop it for a while, pause it with `prefetch_update_monitor` instead. Free.

| Parameter | Type | Default | Description |
| - | - | - | - |
| `id` | string | none | **Required.** |

## Choosing a tool

| You want | Use | Credits |
| - | - | - |
| Pages about something | `prefetch_search` | 2 per 10 results, +1 per page scraped |
| One page's content | `prefetch_scrape` | 1 |
| To know which pages exist | `prefetch_map` | 1 |
| A few specific pages | `prefetch_map`, then `prefetch_scrape` on each | 1 + 1 each |
| A whole section of a site | `prefetch_crawl` with `include_paths` | 1 per page |
| Many known pages | `prefetch_batch_scrape` | 1 per page |
| The merchant behind a card transaction | `prefetch_transaction` | 3 |
| Companies' logos to show | `prefetch_logo_urls` | 0 |
| To build UI that matches a site | `prefetch_styleguide` | 10 |
| The same profile for many companies | `prefetch_batch` with `endpoint: "enrich"` | 12 per company |
| Brand, company, and industry | `prefetch_enrich` | 12 |
| Just the brand colors | `prefetch_brand` | 10 |
| Just the industry | `prefetch_classify` | 5 |
| A picture of the page | `prefetch_screenshot` | 1 |
| An answer that needs searching | `prefetch_answer` | 10, or 100 in `ultra` mode |
| To know when a page changes | `prefetch_create_monitor` | 1 per page, every check |
| What changed, right now | `prefetch_run_monitor` | 1 per page, plus 1 per change judged |


# Migrate from Context.dev
Source: https://docs.prefetch.io/migrate/context-dev

Move scrape, map, crawl, search, answers, brand, styleguide, Logo Link, batches and monitors from Context.dev to Prefetch: endpoint and parameter mapping, and the differences that change behavior.

Most Context.dev endpoints have a direct Prefetch equivalent. The main changes are the base URL, the auth header, snake\_case parameters, and four behaviors worth checking before you switch: caching defaults, crawl regexes, async crawls and the industry taxonomy.

## The basics

| | Context.dev | Prefetch |
| - | - | - |
| Base URL | `https://api.context.dev/v1` | `https://api.prefetch.io` |
| Auth header | `Authorization: Bearer …` | `X-API-Key: …` |
| Parameter style | camelCase (`mainContentOnly`), with some snake\_case | snake\_case (`only_main_content`), except `/brand` and `/enrich` |
| Formats | An object: `"formats": { "markdown": true }` | A list: `"formats": ["markdown"]`, or `formats=markdown,links` on `GET` |
| Cached pages | Scrapes accept copies up to 3 days old by default, crawls 1 day | Fetched live unless you set `max_age` |
| Industry | EIC industry and subindustry, inside the brand profile | IAB category and subcategory, from [`/classify`](/company-data/classify) or [`/enrich`](/company-data/enrich) |
| SDKs | TypeScript, Python, Ruby, Go, PHP | None. Use any HTTP client, or generate one from the [OpenAPI spec](/api-reference/openapi.json). |

To keep Context.dev's scrape caching, send `max_age=259200000` (3 days, in milliseconds).

## Endpoints

| Context.dev | Prefetch |
| - | - |
| `POST /web/scrape` | [`GET` or `POST /scrape`](/web-data/scrape) |
| `GET /web/urls` | [`GET /map`](/web-data/map) |
| `POST /web/crawl` | [`POST /crawl`](/web-data/crawl), then `GET /crawl/{id}` |
| `POST /web/search` | [`GET` or `POST /search`](/web-data/search) |
| `POST /web/answers` | [`POST /answers`](/web-data/answers) |
| `POST /brand/retrieve` | [`GET /brand`](/company-data/brand), or [`GET /enrich`](/company-data/enrich) for brand, company and industry together |
| `GET /brand/search` | [`GET /resolve`](/company-data/resolve) |
| `GET /web/styleguide` | [`GET /styleguide`](/company-data/styleguide) |
| Logo Link (`logos.context.dev`) | [Logo CDN](/company-data/logo-cdn) (`logo.prefetch.io`) |
| `POST /batch/submit` | [`POST /batch/scrape`](/jobs/batches), or [`POST /crawl`](/web-data/crawl) for `"mode": "crawl"` |
| `POST /monitors` and its sub-paths | [`POST /monitor`](/monitors/overview) and its sub-paths |
| `POST /people/search`, `POST /people/enrich`, `POST /company/search`, `POST /news/search`, `POST /parse` | No equivalent |

Prefetch also has endpoints with no Context.dev counterpart: [`/company`](/company-data/company), [`/classify`](/company-data/classify) with IAB categories, [`/screenshot`](/web-data/screenshot), and [batches of brand, enrich, company, classify, screenshot or styleguide](/jobs/batches).

## Scrape

| Context.dev | Prefetch | Notes |
| - | - | - |
| `url` | `url` | |
| `formats: { markdown, html, screenshot, images, json }` | `formats: ["markdown", "html", "screenshot", "images", "json"]` | Prefetch also has `raw_html`, `links` and `summary`. |
| `jsonParams.schema`, `jsonParams.instructions` | `json_schema`, `json_prompt` | |
| `sharedParams.mainContentOnly` | `only_main_content` | |
| `sharedParams.includeSelectors`, `excludeSelectors` | `include_selectors`, `exclude_selectors` | |
| `sharedParams.waitFor` | `wait_for` or `wait_for_selector` | |
| `sharedParams.headers` | `headers` | Requests with headers are never cached on Prefetch. |
| `markdownParams.includeLinks`, `includeImages` | `include_links`, `include_images` | |
| `maxAgeMs` | `max_age` | Milliseconds. Prefetch defaults to a live fetch. |
| `sharedParams.actions`, `profile`, `country`, `viewport` | No equivalent | Prefetch has `mobile` for a phone layout. |
| `formats.product`, `highlights`, `parse`, `bytes` | No equivalent | Use `json` with a schema for product fields. |

### Reading the response

| What | Context.dev | Prefetch |
| - | - | - |
| Markdown | `markdown.data` | `data.markdown.content` |
| Did a format succeed? | `markdown.success` on every output | Formats you didn't ask for are absent. A language model format that failed has `null` values and a reason in `data.warnings`. |
| Page title | `metadata.title` | `data.metadata.title` |
| Cache | `cache_metadata.status` | `data.metadata.cache_state` |

## Map

| Context.dev | Prefetch |
| - | - |
| `domain=stripe.com` | `url=stripe.com` |
| `maxLinks` | `limit` |
| `search` | `search` |
| `includeSubdomains` | `include_subdomains` |
| `urlRegex`, `excludeUrlRegex` | No equivalent. Filter the returned `links` yourself, or use `search`. |
| `sitemapUrl` | No equivalent. Prefetch finds sitemaps through `robots.txt` and the usual locations. Use `sitemap=only` or `skip` to choose sources. |
| Response `urls[]` | Response `data.links[]`, each with `url`, `title`, `description`, `lastmod` and `source` |

## Crawl

Context.dev's `/web/crawl` answers in the same request. Prefetch crawls are [async jobs](/concepts/async-jobs): `POST /crawl` returns an id, and you read pages from `GET /crawl/{id}` or receive them by [webhook](/concepts/webhooks).

| Context.dev | Prefetch | Notes |
| - | - | - |
| `maxPages` (default 100) | `limit` (default 25) | Both stop at 500. |
| `maxDepth` | `max_depth` | |
| `urlRegex`, `excludeUrlRegex` | `include_paths`, `exclude_paths` | Context.dev matches the full URL (`^https?://[^/]+/blog/`). Prefetch matches the path and query (`^/blog/`), so drop the scheme and host from your patterns. Prefetch takes a list of patterns. |
| `followSubdomains` | `allow_subdomains` | |
| `useMainContentOnly` | `scrape_options.only_main_content` | |
| `includeSelectors`, `excludeSelectors` | `scrape_options.include_selectors`, `exclude_selectors` | |
| `waitForMs` | `scrape_options.wait_for` | |
| `maxAgeMs` | `scrape_options.max_age` | |
| Response `results[]` | `data.data[]` on `GET /crawl/{id}`, with `next` for the following page | |

## Search

| Context.dev | Prefetch |
| - | - |
| `query` | `query` |
| `numResults` (1 to 100) | `limit` |
| `includeDomains`, `excludeDomains` | `include_domains`, `exclude_domains` |
| `freshness: "last_24_hours"`, `"last_week"`, `"last_month"`, `"last_year"` | `time_range: "day"`, `"week"`, `"month"`, `"year"`. Prefetch also has `"hour"`. |
| `country`, `languages` | `country`, `language` (two-letter codes) |
| `markdownOptions` | `scrape_options: { "formats": ["markdown"] }` |

## Answers

The request is almost the same:

| Context.dev | Prefetch |
| - | - |
| `task` | `task` |
| `json_format` | `json_format` |
| `mode: "fast"` or `"ultra"` | `mode: "fast"` or `"ultra"`. `ultra` is the REST default on both. |
| `timeoutOpts` | `timeout_opts` |
| `tags` | `tags` |

See [Answers](/web-data/answers).

## Brand

Context.dev's `POST /brand/retrieve` takes a `type`. Each type maps to a different Prefetch call:

| Context.dev `type` | Prefetch |
| - | - |
| `by_domain` with `domain` | `GET /brand?url={domain}`, or `GET /enrich?url={domain}` |
| `by_url` with `direct_url` | `GET /brand?url={page URL}` |
| `by_name` with `name` | `GET /resolve?name={name}`, then `/brand` with the domain |
| `by_email` with `email` | Take the domain from the address, then `/enrich`. See [Enrich signups](/recipes/enrich-signups). |
| `by_transaction` with `transaction_info`, `mcc`, `city`, `country_gl` | `POST /transaction` with `descriptor`, `mcc` and `country` |
| `by_ticker` with `ticker` | No equivalent. `/classify` returns a domain's tickers, but doesn't look a ticker up. |

### Brand fields

| Context.dev `brand.` | Prefetch `data.` |
| - | - |
| `title` | `company.display_name` (from `/company` or `/enrich`) |
| `description`, `slogan` | `classification.description`, `classification.tagline_description` |
| `colors[]` | `brand.colors.brand_colors[]` |
| `logos[]`, with `type` and `mode` | `brand.logos.primary`, `brand.logos.secondary[]`, `favicon_url`, `icon_url` |
| `socials[]`, a list of `{ type, url }` | `brand.social_links` (or `company.social_links` in `/enrich`), an object keyed by platform |
| `address` | `company.addresses[]` |
| `email`, `phone` | `company.emails[]`. There's no phone field. |
| `links` | `company.links` |
| `stock` | `classification.stock_tickers[]` |
| `employees` | `company.employeeCount` |
| `industries.eic[]` | `classification.category` and `subcategory`, in the IAB taxonomy |
| `is_nsfw` | `company.isNsfw` |

## Styleguide

| Context.dev | Prefetch |
| - | - |
| `domain=stripe.com` or `directUrl` | `url` |
| `colorScheme=dark` | `dark_mode=true` |
| `maxAgeMs` | Always read live. A repeat request can come from the request cache. |

Prefetch's styleguide also returns `exports.css` and `exports.tailwind`, ready to paste. See [Styleguide](/company-data/styleguide).

## Logo Link

| Context.dev | Prefetch |
| - | - |
| `https://logos.context.dev/?publicClientId=brandLL_…&domain=stripe.com` | `https://logo.prefetch.io/stripe.com?token=pk_…` |
| `type=icon` | The default. Prefetch serves one square logo per domain. |
| `type=wordmark` | No equivalent |
| `theme=light` or `dark` | No equivalent. Prefetch's `theme` only sets the background a JPEG is flattened onto. |
| A monogram when no logo is known | A letter mark by default. `fallback=404` or `transparent` to change it. |

Prefetch adds `size` (16 to 512 pixels), `format` (`png`, `webp`, `jpeg`) and `greyscale`. Get your token from [`GET /logo/token`](/api-reference/endpoint/logo-token).

## Batches

| Context.dev | Prefetch |
| - | - |
| `input.mode: "scrape"` with `input.data.urls[]` | `POST /batch/scrape` with `urls[]`, up to 500 per batch |
| `input.mode: "crawl"` | `POST /crawl` |
| `input.data.formats`, `sharedParams`, `jsonParams` | `scrape_options`, with the same fields `/scrape` takes |
| Per-URL `itemId` and `meta` | No equivalent. Results carry their `url`. Key your records on it. |
| `webhook` or `webhookUrl` | `webhook` |
| `GET /batch/{id}/results` | `GET /batch/scrape/{id}`, following `next` |

Context.dev reserves credits when you submit and refunds what's unused. Prefetch charges results as they complete, and never for failed pages.

## Monitors

| Context.dev | Prefetch |
| - | - |
| `target: { type: "page", url }` | `targets: [{ type: "scrape", urls: [url] }]`. One monitor can hold up to 50 targets. |
| `target: { type: "page", instructions }` | A `scrape` target plus a `goal` on the monitor |
| `target: { type: "extract", schema, instructions }` | A `scrape` target with `change_tracking: { modes: ["json"], json_schema, json_prompt }` |
| `target: { type: "sitemap" }` | A `crawl` target, which reports pages that appear and disappear |
| `target: { type: "search", query }` | `targets: [{ type: "search", queries: [query] }]` |
| `include_selectors`, `exclude_selectors` | `scrape_options.include_selectors` and `exclude_selectors` on the target |
| `schedule: { type: "interval", frequency: 6, unit: "hours" }` | `schedule: { text: "every 6 hours" }`, or `cron` with a `timezone` |
| Runs and changes | Checks, and the pages in each check marked `changed`, `new` or `removed` |
| `POST /monitors/{id}/run` | `POST /monitor/{id}/run` |
| Webhooks | `webhook` and email alerts. See [Alerts](/monitors/alerts). |

See [Monitors](/monitors/overview) for targets, schedules and judging.

## Webhooks

Both sign deliveries the same way: `t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">`. Change the header you read from `X-Context-Signature` to `X-Prefetch-Signature`, and use the secret Prefetch returns when you create the job or monitor. See [Verify signatures](/concepts/webhooks#verify-signatures).

## Errors

Both return a machine-readable `error_code`. Prefetch adds `retryable`, so you can decide whether to retry without a list of codes. A request over your credit balance returns `403` with `CREDITS_EXHAUSTED` on Prefetch, where Context.dev returns `402`. See [Error handling](/concepts/errors).

## Checklist

* [ ] Swap the base URL and the auth header.
* [ ] Turn `formats` objects into lists, and rename parameters to snake\_case.
* [ ] Set `max_age` wherever you relied on Context.dev's default caching.
* [ ] Rewrite crawl regexes to match paths, and poll or webhook for crawl results.
* [ ] Map EIC industries to IAB categories where you store them.
* [ ] Update your webhook signature header and secrets.


# Migrate from Firecrawl
Source: https://docs.prefetch.io/migrate/firecrawl

Move scrape, map, crawl, batch scrape, search and monitors from Firecrawl's v2 API to Prefetch: endpoint and parameter mapping, response differences and webhooks.

Prefetch's web data endpoints work much like Firecrawl's v2 API, so most migrations are a change of base URL, header and parameter spelling. This page maps one to the other.

## The basics

| | Firecrawl v2 | Prefetch |
| - | - | - |
| Base URL | `https://api.firecrawl.dev/v2` | `https://api.prefetch.io` |
| Auth header | `Authorization: Bearer fc-…` | `X-API-Key: …` |
| Parameter style | camelCase | snake\_case |
| Response envelope | `{ success, data }` | `{ success, data, meta }`, and errors add `error_code` and `retryable` |
| Cached pages | Served up to 2 days old by default (`maxAge`) | Fetched live unless you set `max_age` |

To keep Firecrawl's caching behavior, send `max_age=172800000` (2 days, in milliseconds).

## Endpoints

| Firecrawl v2 | Prefetch |
| - | - |
| `POST /v2/scrape` | [`GET` or `POST /scrape`](/web-data/scrape) |
| `POST /v2/map` | [`GET /map`](/web-data/map) |
| `POST /v2/crawl` | [`POST /crawl`](/web-data/crawl) |
| `GET /v2/crawl/{id}` | `GET /crawl/{id}` |
| `DELETE /v2/crawl/{id}` | `DELETE /crawl/{id}` |
| `GET /v2/crawl/{id}/errors` | `GET /crawl/{id}/errors` |
| `POST /v2/batch/scrape` | [`POST /batch/scrape`](/jobs/batches) |
| `GET /v2/batch/scrape/{id}` | `GET /batch/scrape/{id}` |
| `POST /v2/search` | [`GET` or `POST /search`](/web-data/search) |
| `/v2/monitor` and its sub-paths | [`/monitor`](/monitors/overview) and the same sub-paths |

Prefetch also has company data endpoints with no Firecrawl equivalent: [`/enrich`](/company-data/enrich), [`/brand`](/company-data/brand), [`/company`](/company-data/company), [`/classify`](/company-data/classify), [`/styleguide`](/company-data/styleguide), [`/resolve`](/company-data/resolve), [`/transaction`](/company-data/transaction) and the [logo CDN](/company-data/logo-cdn).

## Scrape

| Firecrawl | Prefetch | Notes |
| - | - | - |
| `url` | `url` | |
| `formats: ["markdown", "html", "rawHtml", "links", "screenshot", "summary"]` | `formats: ["markdown", "html", "raw_html", "links", "screenshot", "summary"]` | Prefetch also has `images`. On `GET`, pass a comma-separated list. |
| `formats: [{ "type": "json", "prompt": "…", "schema": {…} }]` | `formats: ["json"]` with `json_prompt` and `json_schema` | |
| `onlyMainContent` | `only_main_content` | Both default to `true`. |
| `includeTags`, `excludeTags` | `include_selectors`, `exclude_selectors` | CSS selectors. |
| `waitFor` | `wait_for` | Milliseconds. Prefetch also has `wait_for_selector`. |
| `maxAge` | `max_age` | Milliseconds. Prefetch defaults to a live fetch. |
| `mobile` | `mobile` | |
| `headers` | `headers` | Requests with headers are never cached on Prefetch. |
| `removeBase64Images` (default `true`) | `include_base64_images` (default `false`) | Inverted name, same default behavior. |
| `checkPromptInjection` | `check_prompt_injection` | |

## Map

| Firecrawl | Prefetch |
| - | - |
| `url`, `search`, `limit` | `url`, `search`, `limit` |
| `sitemap: "include" \| "only" \| "skip"` | `sitemap: "include" \| "only" \| "skip"` |
| `includeSubdomains` | `include_subdomains` |
| `ignoreQueryParameters` | `ignore_query_params` |

## Crawl

| Firecrawl | Prefetch | Notes |
| - | - | - |
| `limit` | `limit` | Prefetch caps a crawl at 500 pages. |
| `maxDiscoveryDepth` | `max_depth` | Sitemap pages are depth 0 on both. |
| `includePaths`, `excludePaths` | `include_paths`, `exclude_paths` | Regular expressions, matched against the path and query on Prefetch. |
| `allowSubdomains`, `allowExternalLinks`, `crawlEntireDomain` | `allow_subdomains`, `allow_external_links`, `crawl_entire_domain` | |
| `sitemap: "include"` or `"skip"` | `use_sitemap: true` or `false` | For `"only"`, send `use_sitemap: true` with `max_depth: 0`. |
| `ignoreRobotsTxt` | `respect_robots_txt: false` | |
| `delay` (seconds) | `delay_ms` (milliseconds) | |
| `maxConcurrency` | `concurrency` | 1 to 5 on Prefetch. |
| `scrapeOptions` | `scrape_options` | Takes everything `/scrape` takes. |
| `webhook` | `webhook` | See [Webhooks](#webhooks) below. |

## Batch scrape

Firecrawl takes scrape options at the top level of a batch. Prefetch nests them in `scrape_options`:

```json theme={"theme":"css-variables"}
{
  "urls": ["https://example.com/a", "https://example.com/b"],
  "scrape_options": { "formats": ["markdown"], "only_main_content": true },
  "ignore_invalid_urls": true,
  "concurrency": 3
}
```

`ignoreInvalidURLs` becomes `ignore_invalid_urls`, and `maxConcurrency` becomes `concurrency`.

## Search

| Firecrawl | Prefetch |
| - | - |
| `query`, `limit`, `location`, `country` | `query`, `limit`, `location`, `country` |
| `sources: ["web"]` or `["news"]` | `type: "web"` or `"news"` |
| `tbs: "qdr:w"` | `time_range: "week"` (`hour`, `day`, `week`, `month`, `year`) |
| `includeDomains`, `excludeDomains` | `include_domains`, `exclude_domains` |
| `scrapeOptions` | `scrape_options` |

## Reading responses

| What | Firecrawl | Prefetch |
| - | - | - |
| Scraped markdown | `data.markdown` (a string) | `data.markdown.content` |
| Source URL | `data.metadata.sourceURL` | `data.metadata.source_url` |
| Status code | `data.metadata.statusCode` | `data.status_code` |
| Search results | `data.web[]` | `data.results[]`, each with `scrape` when you asked for content |
| Crawl pages | `data[]` on the status response | `data.data[]`, with `next` for the following page |

Each Prefetch format is an object with counts and flags, such as `markdown.word_count` and `markdown.truncated`. See [Scrape](/web-data/scrape#example-response).

## Errors

Both return `success: false` with an `error` message. Prefetch adds a stable `error_code` and a `retryable` flag, so you can branch on them instead of parsing the message. See [Error handling](/concepts/errors).

## Webhooks

Crawl and batch event names carry over: `crawl.started`, `crawl.page`, `crawl.completed`, and `batch_scrape.*`. Signatures differ:

| | Firecrawl | Prefetch |
| - | - | - |
| Header | `X-Firecrawl-Signature` | `X-Prefetch-Signature: t=<unix seconds>,v1=<hex>` |
| What's signed | The raw body | `<t>.<raw body>`, so you can reject replays older than five minutes |
| Secret | One per account, in your settings | One per job or monitor, returned when you create it |

See [Verify signatures](/concepts/webhooks#verify-signatures) for code.

## Checklist

* [ ] Swap the base URL and the auth header.
* [ ] Rename parameters to snake\_case, and nest batch scrape options in `scrape_options`.
* [ ] Read `data.markdown.content` instead of `data.markdown`.
* [ ] Set `max_age` wherever you relied on Firecrawl's default caching.
* [ ] Update your webhook signature check.
* [ ] Branch on `error_code` and `retryable`.


# Migrate from Clearbit or Brandfetch logos
Source: https://docs.prefetch.io/migrate/logos

Replace logo.clearbit.com or cdn.brandfetch.io logo URLs with the Prefetch logo CDN, and move Brandfetch's Brand, Search and Transaction APIs to Prefetch.

The Prefetch [logo CDN](/company-data/logo-cdn) serves any domain's logo from a URL you put straight in an `<img>` tag. Logo requests cost no credits: each plan includes a monthly logo quota.

```html theme={"theme":"css-variables"}
<img src="https://logo.prefetch.io/stripe.com?token=pk_YOUR_TOKEN&size=64" width="32" height="32" alt="Stripe" />
```

## Before you start

Get your publishable logo token once. It serves logos and nothing else, so it's safe in browser code:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/logo/token" -H "X-API-Key: $PREFETCH_API_KEY"
```

The response has `token`, your `quota` for the month and how much you've `used`. See [Logo CDN](/company-data/logo-cdn#your-token).

## From Clearbit

Clearbit's Logo API shut down in December 2025, so any `logo.clearbit.com` URL still in your code no longer loads. Its parameters map one to one:

| Clearbit | Prefetch |
| - | - |
| `https://logo.clearbit.com/stripe.com` | `https://logo.prefetch.io/stripe.com?token=pk_…` |
| `size=128` | `size=128` (16 to 512 pixels, square) |
| `format=png` or `format=jpg` | `format=png`, `jpeg` (`jpg` works too) or `webp` |
| `greyscale=true` | `greyscale=true` |
| A missing logo returns `404` | A missing logo returns a letter mark. Add `fallback=404` to keep the old behavior. |

Most code only needs its base URL changed and the token added:

```javascript JavaScript theme={"theme":"css-variables"}
const LOGO_TOKEN = process.env.NEXT_PUBLIC_PREFETCH_LOGO_TOKEN;

// Before: `https://logo.clearbit.com/${domain}?size=128`
export function logoUrl(domain, size = 128) {
  return `https://logo.prefetch.io/${domain}?token=${LOGO_TOKEN}&size=${size}`;
}

// Or rewrite stored Clearbit URLs as you read them
export function fromClearbit(url) {
  const u = new URL(url);
  const out = new URL(`https://logo.prefetch.io${u.pathname}`);
  out.searchParams.set("token", LOGO_TOKEN);
  for (const key of ["size", "format", "greyscale"]) {
    if (u.searchParams.has(key)) out.searchParams.set(key, u.searchParams.get(key));
  }
  return out.toString();
}
```

```python Python theme={"theme":"css-variables"}
import os
from urllib.parse import urlsplit, parse_qs, urlencode

LOGO_TOKEN = os.environ["PREFETCH_LOGO_TOKEN"]

def logo_url(domain, size=128):
    return f"https://logo.prefetch.io/{domain}?" + urlencode({"token": LOGO_TOKEN, "size": size})

def from_clearbit(url):
    parts = urlsplit(url)
    query = {k: v[0] for k, v in parse_qs(parts.query).items() if k in ("size", "format", "greyscale")}
    return f"https://logo.prefetch.io{parts.path}?" + urlencode({"token": LOGO_TOKEN, **query})
```

If your UI hid the image or showed initials when Clearbit returned `404`, you can drop that code: the default letter mark already fills the space. Keep it, and add `fallback=404`, if you'd rather draw your own placeholder.

## From the Brandfetch Logo API

| Brandfetch | Prefetch | Notes |
| - | - | - |
| `https://cdn.brandfetch.io/nike.com` or `…/domain/nike.com` | `https://logo.prefetch.io/nike.com` | |
| `?c=BRANDFETCH_CLIENT_ID` | `?token=pk_…` | Both are publishable and safe in browser code. |
| `/w/128/h/128` | `size=128` | Prefetch logos are square, 16 to 512 pixels, centered on a transparent background. |
| `/type/icon` (the default) | The default | Prefetch serves one square logo per domain. |
| `/type/logo`, `/type/symbol` | No equivalent | For other variants, [`/brand`](/company-data/brand) returns `logos.primary` and `logos.secondary`. |
| `/theme/light`, `/theme/dark` | No equivalent | Brandfetch picks a logo variant for the background. Prefetch's `theme` only sets the color a JPEG is flattened onto. PNG and WebP stay transparent. |
| `/fallback/lettermark` | `fallback=monogram` (the default) | |
| `/fallback/transparent` | `fallback=transparent` | |
| `/fallback/404` | `fallback=404` | |
| `/fallback/brandfetch` | No equivalent | |
| File extension: `.png`, `.jpg`, `.webp` (default) or `.svg` | `format=png` (default), `jpeg` or `webp` | Prefetch doesn't serve SVG from the CDN. `/brand` returns SVG logos when the site has them. |
| Greyscale with a CSS `filter` | `greyscale=true` | |
| `/ticker/NKE`, `/isin/…`, `/crypto/BTC` | No equivalent | Prefetch looks logos up by domain only. Map tickers to domains on your side first. |

```html theme={"theme":"css-variables"}
<!-- Before -->
<img src="https://cdn.brandfetch.io/domain/nike.com/w/128/h/128/fallback/lettermark/type/icon?c=BRANDFETCH_CLIENT_ID" alt="Nike" />

<!-- After -->
<img src="https://logo.prefetch.io/nike.com?token=pk_YOUR_TOKEN&size=128" alt="Nike" />
```

## From Brandfetch's other APIs

| Brandfetch | Prefetch | Notes |
| - | - | - |
| Brand API: `GET https://api.brandfetch.io/v2/brands/domain/{domain}` | [`GET /brand?url={domain}`](/company-data/brand) | Logos, colors, fonts, images and social links. [`/enrich`](/company-data/enrich) adds company details and industry for 12 credits. |
| Brand API by ticker, ISIN or crypto symbol | No equivalent | Prefetch takes a domain or URL. |
| Brand Search API: `GET /v2/search/{name}` | [`GET /resolve?name={name}`](/company-data/resolve) | Ranked domains with a confidence score. It also completes partial names for typeahead. |
| Transaction API: `POST /v2/brands/transaction` with `transactionLabel` and `countryCode` | [`POST /transaction`](/company-data/transaction) with `descriptor` and `country` | Returns the merchant, its website, processor, location and a ready-to-use `logo_url`. |

Prefetch authenticates REST calls with an `X-API-Key` header instead of `Authorization: Bearer`. See [Authentication](/concepts/authentication).

## Checklist

* [ ] Get your logo token from `GET /logo/token`.
* [ ] Replace the base URL and add `token` to every logo URL.
* [ ] Map `w`/`h` or `size` to `size`, and the file extension to `format`.
* [ ] Decide on `fallback`: the letter mark, `transparent` or `404`.
* [ ] Check your plan's [logo quota](/company-data/logo-cdn#quotas). Browsers cache each logo for a day, so repeat views don't count.


# Alerts
Source: https://docs.prefetch.io/monitors/alerts

Get a monitor's changes by webhook, by email, or both.

A monitor can tell you about changes in two ways. You can use both on one monitor, or neither and read the checks yourself.

## Webhooks

With a `webhook`, two events are posted to you:

| Event | When |
| - | - |
| [`monitor.page`](/api-reference/endpoint/monitor-webhook-page) | A page changed, appeared, was removed, or started failing, and, with a goal, the judge ruled it meaningful |
| [`monitor.check.completed`](/api-reference/endpoint/monitor-webhook-check) | A check finished, with its summary counts |

```json theme={"theme":"css-variables"}
{
  "webhook": {
    "url": "https://you.example.org/hooks/prefetch",
    "headers": { "Authorization": "Bearer your-token" },
    "metadata": { "env": "production" },
    "events": ["monitor.page"]
  }
}
```

The URL must use `https://`. Every request is signed with the monitor's `webhook.secret`. Answer `2xx` within 10 seconds. Failures are retried after 1, 5 and 15 minutes. See [Webhooks](/concepts/webhooks) for signature verification.

A page that fails sends one `monitor.page` event, when it starts failing. Set `notify_errors_after` (1 to 10) to send it only once a page has failed that many checks in a row, so a site that blips once and recovers sends nothing.

## Email

Add `email` to have changes emailed to up to 5 addresses:

```json theme={"theme":"css-variables"}
{ "email": { "to": ["you@example.com", "teammate@example.com"] } }
```

Each check that finds changes sends **one email** to every active address. It lists the pages that changed, appeared or were removed, with the judge's reason and the changed lines or fields. Up to 20 pages are listed, and the rest are counted.

The same rules as the `monitor.page` webhook decide what counts. The baseline is never emailed, and with a goal, changes ruled not meaningful are left out. A page that fails to load is counted in the email, not emailed on its own.

Emails are free. They never cost credits.

### Confirming addresses

Each address has to agree to the emails before anything is sent:

| Address | What happens |
| - | - |
| The email on your Prefetch account, or anyone's in your organization | `active` straight away |
| Any other address | Gets one confirmation email, and stays `pending` until its owner selects **Confirm**. The link expires after 7 days. |

Every email has an unsubscribe link, and supports one-click unsubscribe in mail clients that offer it. An address that unsubscribes shows as `unsubscribed` and gets nothing more from that monitor, even if you keep it in the list. To ask it again, remove the address and add it back.

`email.recipients` in the response shows each address's status. If a pending address never got its confirmation, send it again with a `PATCH`:

```json theme={"theme":"css-variables"}
{ "email": { "to": ["teammate@example.com"], "resend_confirmation": true } }
```

> [!NOTE]
>
> An address can be asked to confirm at most 3 times a day, from any number of monitors, and one API key can send at most 20 confirmation emails a day. A request over either limit is refused with `429` and changes nothing.

## Reading changes yourself

Without a webhook or email, read each check with [`GET /monitor/{id}/checks/{checkId}`](/api-reference/endpoint/monitor-check), or list recent checks with [`GET /monitor/{id}/checks`](/api-reference/endpoint/monitor-checks). Over MCP, `prefetch_get_monitor_check` shows the latest check.


# Detecting changes
Source: https://docs.prefetch.io/monitors/change-detection

How a monitor decides a page changed: text diffs, tracked JSON fields, and the options that keep noise out.

Each page in each check gets one status:

| Status | Meaning |
| - | - |
| `same` | Fetched again, and nothing changed. |
| `new` | Seen for the first time: on the first check, or a page that appeared since. |
| `changed` | Fetched again, and the content differs. The page carries a `diff`. |
| `removed` | A page the monitor knew answered 404 or 410, or a crawl that ran to completion no longer finds it. Reported once. |
| `error` | Couldn't be checked. The last good snapshot is kept, so the next good check compares against it. |

## Text mode

By default the page's **markdown** is compared. `diff.text` holds a unified diff, and `diff.hunks` has the same hunks as structured lines.

Rendering noise never counts as a change: whitespace and line endings, invisible characters and non-breaking spaces, and the tracking, session and signature parameters in link URLs (`utm_source`, `fbclid`, `jsessionid`, signed CDN URLs). A page that loads but renders no text at all is reported as an `error`, not as every line removed.

## JSON mode

To watch specific facts instead of the whole text, use **json** mode. Describe the fields, and each check extracts them and compares them one by one:

```json theme={"theme":"css-variables"}
{
  "type": "scrape",
  "urls": ["https://example.com/pricing"],
  "change_tracking": { "modes": ["json"], "json_prompt": "Each plan: name, monthly price, headline features" }
}
```

A page is then `changed` only when a tracked field changes, and `diff.fields` says exactly which one: `plans[0].price: "$19/mo" → "$24/mo"`. Pass `json_schema` instead of, or as well as, `json_prompt` to fix the shape. Use `"modes": ["json", "markdown"]` to get both diffs.

The extraction runs again only when the page's text changed. An unchanged page keeps its last extraction, so a model reading identical text a little differently is never a change, and costs nothing. List items are matched by identity (an `id`, `url`, `name` or `title` field), so one job inserted at the top of a list is one `added` field, not every job shifted.

## Cutting noise

Most false alarms come from page furniture: a "last updated" date, a rotating testimonial, a visitor counter. These `change_tracking` options keep them quiet:

| Option | What it does |
| - | - |
| `ignore_text` | Up to 25 phrases. Lines that contain one are left out of the comparison. Plain text, case-insensitive, with `*` for anything: `["people are viewing", "viewed * times"]`. |
| `ignore_dates` | Masks dates, times and "3 minutes ago" before comparing. |
| `ignore_order` | Lines that only moved aren't a change. |
| `notify_on` | Which kinds of change notify you: `added`, `removed` or `changed` lines or fields. For a crawl, that's pages that appear or disappear. `["added"]` tells you about new job posts, not filled ones. |
| `only_new_content` | Notify only when a change brings text the page hasn't shown recently, so content that cycles (a carousel, A/B variants) stays quiet. |

`ignore_text`, `ignore_dates` and `ignore_order` change only what's compared. A change still shows the page as it reads.

`notify_on` and `only_new_content` decide whether a change notifies you. The page is still recorded as `changed`, and `diff.alert` says why it was held back.

Changing any of these options re-baselines the target's pages silently, instead of reporting them all as changed.

> [!TIP]
>
> You can also leave parts of the page out with `scrape_options.exclude_selectors`, or switch to json mode and track only what you care about. Images are left out of the comparison by default, because their URLs change with every deploy.

## Reading a change

[`GET /monitor/{id}/checks/{checkId}?status=changed`](/api-reference/endpoint/monitor-check) lists the pages that changed in one check, with their diffs, the judge's verdict and, in json mode, the full current extraction.


# Goals and judging
Source: https://docs.prefetch.io/monitors/goals

Describe in one sentence what you want to hear about, and every change is judged against it before you're alerted.

Add a `goal`, one plain sentence about what you want to be told, and every changed, new or removed page is judged against it:

```json theme={"theme":"css-variables"}
{ "goal": "Alert me when a plan price or its included features change" }
```

Each judged page gets `is_meaningful` and a `judgment` with a `reason`. Pages ruled **not meaningful** are still recorded on the check, but they don't send a webhook or an email.

```json theme={"theme":"css-variables"}
{
  "is_meaningful": true,
  "judgment": {
    "meaningful": true,
    "confidence": "high",
    "reason": "The Starter plan's price went from $19 to $24 a month.",
    "meaningful_changes": [
      { "type": "changed", "before": "$19/mo", "after": "$24/mo", "reason": "A plan price changed." }
    ]
  }
}
```

Judging is on whenever a goal is set. Pass `judge_enabled: false` to keep the goal without judging. The first check's baseline is never judged.

## Writing a good goal

* **Restate the scope:** "the Pro plan", "the top 10 results", "API changes".
* **Name exclusions only when they matter:** "Ignore changes to customer logos."
* **Ask for what you want, even if it's usually noise.** If the goal asks about a timestamp or a counter, it gets it. If it says to ignore something, that thing never counts.

## How the judge works

* Page content is treated as data, never as instructions. Text on a page can't talk the judge out of an alert.
* On a long diff, the judge reads the parts most relevant to your goal, not just the first ones.
* `meaningful_changes` quote the page exactly. A quote the judge wasn't shown is dropped.
* A page that flips back to a version it has shown before isn't judged again. The earlier verdict is reused, for free.

## Credits

Each judged page costs 1 credit. Only changed, new and removed pages are judged, and only when the monitor has a goal. See [Limits and credits](/monitors/limits).

## Changing the goal

Send a new `goal` with [`PATCH /monitor/{id}`](/api-reference/endpoint/monitor-update), or `null` to stop judging and hear about every change. Try a new goal straight away with [`POST /monitor/{id}/run`](/api-reference/endpoint/monitor-run).


# Limits and credits
Source: https://docs.prefetch.io/monitors/limits

What a monitor check costs, what happens when credits run out, and what each plan allows.

## What a check costs

Creating, reading, changing and deleting a monitor is free. **Each check** is billed to the API key that created the monitor:

| What | Credits |
| - | - |
| Each page fetched | 1, the [`/scrape`](/web-data/scrape) rate |
| A `json` target's extraction | +3, and only when the page's text changed |
| Each search a `search` target runs | 2, the [`/search`](/web-data/search) rate, +1 per new result read |
| Each page judged against your goal | 1. Only changed, new or removed pages are judged. A verdict reused from before is free. |

Pages that fail to load are never charged, and neither are skipped checks.

`estimated_credits_per_check` and `estimated_credits_per_month` on every monitor are upper bounds: they assume every page is fetched and judged on every check. `actual_credits` on a finished check is what you paid.

For example, a check of 18 pages where one page tracks `json` and changed, and 3 pages were judged, costs 18 + 3 + 3 = 24 credits.

## When credits run out

A check never spends more than its key has left. If credits run out partway, the check stops and reports `partial`. If the key has none at all, the check is recorded as `skipped_no_credits`, and the monitor keeps its schedule and resumes as soon as credits refill.

## Automatic pausing

A monitor whose every page has failed for 10 checks in a row, over at least 24 hours, is paused, and its email recipients are told. Failed pages are never billed, so this only stops it retrying a page that's gone or blocks every fetch. Set `status` back to `"active"` once the pages load.

## Limits

| Limit | Value |
| - | - |
| Targets per monitor | 50 |
| URLs per scrape target | 100 |
| Searches per search target | 5, of up to 20 results each |
| Pages per check, across all targets | 500 |

The rest depend on your plan:

| Limit | Free | Starter | Pro | Growth | Scale |
| - | - | - | - | - | - |
| Shortest schedule | Hourly | Every 5 minutes | Every 5 minutes | Every 2 minutes | Every minute |
| Monitors per API key | 5 | 50 | 250 | 1,000 | 5,000 |
| Pages per check | 10 | 500 | 500 | 500 | 500 |
| Check history (`retention_days`, 30 by default) | Up to 30 days | Up to 365 | Up to 365 | Up to 365 | Up to 365 |
| Email addresses per monitor | 1, your account's | 5 | 5 | 5 | 5 |
| Pages that block bots | Not retried | Retried through a stealth browser and proxies | Retried | Retried | Retried |

A request that asks for more than your plan allows is refused, and the error names the limit.

A monitor made on a bigger plan keeps running after a downgrade. A schedule that's now too frequent moves to the fastest your plan allows, and its email recipients are told once. Its history is cut to your plan's window.

A check that runs longer than 30 minutes stops and reports `partial`.


# Monitors
Source: https://docs.prefetch.io/monitors/overview

Watch pages, sites and searches on a schedule, and get a webhook or an email with just what changed. Free to create; each check is billed per page.

A monitor checks pages on a schedule and compares each one with the previous check. Instead of polling a pricing page, a changelog or a policy page yourself, you get a webhook or an email with just the change.

**1. Create**

`POST /monitor` with what to watch, how often, and optionally a goal that describes which changes matter.

**2. Baseline**

The first check records every page. Nothing is announced, because every page is new.

**3. Check**

Each scheduled check fetches every page again and marks it `same`, `new`, `changed`, `removed` or `error`, with a diff.

**4. Get told**

Changes that match your goal are posted to your webhook and emailed to your addresses. You can also read any check with [`GET /monitor/{id}/checks/{checkId}`](/api-reference/endpoint/monitor-check).

## Example request

This monitor watches a competitor's pricing page for price changes and their changelog for new posts, every weekday morning:

```bash cURL theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/monitor" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Competitor pricing",
    "schedule": { "text": "every weekday at 9am", "timezone": "Europe/Athens" },
    "goal": "Alert me when a plan price or its included features change",
    "targets": [
      {
        "type": "scrape",
        "urls": ["https://example.com/pricing"],
        "change_tracking": { "modes": ["json"], "json_prompt": "Each plan: name, monthly price, headline features" }
      },
      {
        "type": "crawl",
        "url": "https://example.com/changelog",
        "crawl_options": { "limit": 25, "include_paths": ["^/changelog/"] }
      }
    ],
    "webhook": { "url": "https://you.example.org/hooks/prefetch" },
    "email": { "to": ["you@example.com"] }
  }'
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/monitor", {
  method: "POST",
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    name: "Competitor pricing",
    schedule: { text: "every weekday at 9am", timezone: "Europe/Athens" },
    goal: "Alert me when a plan price or its included features change",
    targets: [
      {
        type: "scrape",
        urls: ["https://example.com/pricing"],
        change_tracking: { modes: ["json"], json_prompt: "Each plan: name, monthly price, headline features" },
      },
      {
        type: "crawl",
        url: "https://example.com/changelog",
        crawl_options: { limit: 25, include_paths: ["^/changelog/"] },
      },
    ],
    webhook: { url: "https://you.example.org/hooks/prefetch" },
    email: { to: ["you@example.com"] },
  }),
});

const { data } = await res.json();
console.log(data.id, data.schedule.cron, data.webhook.secret);
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.post(
    "https://api.prefetch.io/monitor",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
    json={
        "name": "Competitor pricing",
        "schedule": {"text": "every weekday at 9am", "timezone": "Europe/Athens"},
        "goal": "Alert me when a plan price or its included features change",
        "targets": [
            {
                "type": "scrape",
                "urls": ["https://example.com/pricing"],
                "change_tracking": {"modes": ["json"], "json_prompt": "Each plan: name, monthly price, headline features"},
            },
            {
                "type": "crawl",
                "url": "https://example.com/changelog",
                "crawl_options": {"limit": 25, "include_paths": ["^/changelog/"]},
            },
        ],
        "webhook": {"url": "https://you.example.org/hooks/prefetch"},
        "email": {"to": ["you@example.com"]},
    },
)
monitor = r.json()["data"]
print(monitor["id"], monitor["webhook"]["secret"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "mon_3f9a1c2b7d4e4f6a8b0c1d2e3f4a5b6c",
    "name": "Competitor pricing",
    "status": "active",
    "schedule": { "cron": "0 9 * * 1-5", "timezone": "Europe/Athens", "text": "every weekday at 9am" },
    "next_run_at": "2026-10-12T06:00:00.000Z",
    "last_run_at": null,
    "current_check_id": null,
    "goal": "Alert me when a plan price or its included features change",
    "judge_enabled": true,
    "targets": [
      { "id": "tgt_8d1e0f2a3b4c5d6e", "type": "scrape", "urls": ["https://example.com/pricing"], "...": "every option, with its effective value" },
      { "id": "tgt_1a2b3c4d5e6f7a8b", "type": "crawl", "url": "https://example.com/changelog", "...": "..." }
    ],
    "webhook": {
      "url": "https://you.example.org/hooks/prefetch",
      "headers": {},
      "metadata": {},
      "events": ["monitor.page", "monitor.check.completed"],
      "secret": "whsec_4f1c9e2a7b3d8e6f0a5c1b9d2e7f3a8c4b6d0e1f9a2c5b7d"
    },
    "email": {
      "to": ["you@example.com"],
      "recipients": [
        { "address": "you@example.com", "status": "active", "confirmation_sent_at": null, "confirmed_at": "2026-10-09T10:00:00.000Z", "unsubscribed_at": null }
      ]
    },
    "retention_days": 30,
    "estimated_credits_per_check": 55,
    "estimated_credits_per_month": 1155,
    "last_check_summary": null,
    "created_at": "2026-10-09T10:00:00.000Z",
    "updated_at": "2026-10-09T10:00:00.000Z"
  },
  "meta": {
    "requestId": "b8f1d2e3-4a5b-4c6d-8e7f-9a0b1c2d3e4f",
    "durationMs": 61
  }
}
```

The status is `201 Created`. Keep the `webhook.secret`: you need it to [verify each webhook](/concepts/webhooks#verify-signatures). You can read it again with [`GET /monitor/{id}`](/api-reference/endpoint/monitor-get).

To take the baseline straight away instead of waiting for the schedule, call [`POST /monitor/{id}/run`](/api-reference/endpoint/monitor-run).

## The parts of a monitor

> [card] [Targets](/monitors/targets)
>
> Fixed pages, a whole site section, or a web search.

> [card] [Schedules](/monitors/schedules)
>
> Plain phrases or cron, in any timezone.

> [card] [Detecting changes](/monitors/change-detection)
>
> Text diffs, tracked JSON fields, and how to cut noise.

> [card] [Goals and judging](/monitors/goals)
>
> One sentence that decides which changes you hear about.

> [card] [Alerts](/monitors/alerts)
>
> Webhooks and email.

> [card] [Limits and credits](/monitors/limits)
>
> What a check costs, and what each plan allows.

## Credits

Creating, reading and changing a monitor is free. **Each check** costs 1 credit per page fetched, plus extra for `json` extraction, search targets and judging. See [Limits and credits](/monitors/limits).

> [!WARNING]
>
> A monitor bills on every check for as long as it's active. A crawl target with `limit: 100` on a 5-minute schedule fetches 28,800 pages a day. Start small, and pause monitors you aren't using.

> [!NOTE]
>
> Monitors need a direct Prefetch API key. They aren't available through RapidAPI, which bills from a response header, and a scheduled check runs when there's no response to carry one.


# Schedules
Source: https://docs.prefetch.io/monitors/schedules

Set how often a monitor checks, as a plain phrase or five-field cron, in any timezone.

Write the schedule as a phrase or as five-field cron, in any IANA timezone:

```json theme={"theme":"css-variables"}
{ "schedule": { "text": "every weekday at 9am", "timezone": "America/New_York" } }
```

```json theme={"theme":"css-variables"}
{ "schedule": { "cron": "*/30 * * * *" } }
```

Phrases you can use include `every 30 minutes`, `every 15 minutes starting at :07`, `hourly`, `every 2 hours`, `daily`, `daily at 9am`, `daily at 5:30 PM`, `every weekday at 9am`, `weekly`, `every monday at 8:00` and `monthly`.

## Rules

* Runs must be **as far apart as your plan requires**, for every gap, not just the first:

  | Plan | Shortest gap |
  | - | - |
  | Free | 1 hour |
  | Starter, Pro | 5 minutes |
  | Growth | 2 minutes |
  | Scale | 1 minute |

* Phrases that leave the minute open (`hourly`, `daily`) get a fixed minute of their own, so monitors created at the same time don't all fire at once.

* The response always shows the cron the monitor actually runs on, in `schedule.cron`.

* Times follow the timezone across daylight-saving changes.

## One check at a time

A monitor runs one check at a time. A check that comes due while the previous one is still running is recorded as `skipped_overlap` instead of running alongside it, and isn't charged.

## Running a check now

[`POST /monitor/{id}/run`](/api-reference/endpoint/monitor-run) runs a check outside the schedule, without moving it. Use it to take the first baseline right after you create a monitor, or to try a new goal. It works on paused monitors too.

## Pausing

Set `"status": "paused"` with [`PATCH /monitor/{id}`](/api-reference/endpoint/monitor-update). A paused monitor keeps its settings and history but runs no checks, so it costs nothing. Set `"status": "active"` to resume. Runs missed while paused aren't made up.


# Targets
Source: https://docs.prefetch.io/monitors/targets

What a monitor watches: a fixed list of pages, a whole site section, or a web search.

A monitor has up to 50 **targets**, of three kinds. You can mix them in one monitor.

| Target | Watches | Each check |
| - | - | - |
| `scrape` | A fixed list of up to 100 URLs | Fetches each page the way [`/scrape`](/web-data/scrape) would, rendering JavaScript and getting past bot protection |
| `crawl` | A site, or a section of one | Re-crawls it with the options [`/crawl`](/web-data/crawl) takes, so pages that appear or disappear are reported too |
| `search` | Up to 5 web searches | Runs each search the way [`/search`](/web-data/search) would. A result the target hasn't seen before is `new`. |

One check fetches at most **500 pages** across all targets: every scrape URL, every crawl's `limit`, and every search's result `limit`.

## Scrape targets

Use a scrape target when you know exactly which pages matter, such as a pricing page or a terms of service.

```json theme={"theme":"css-variables"}
{
  "type": "scrape",
  "urls": ["https://example.com/pricing", "https://example.com/terms"],
  "scrape_options": { "exclude_selectors": [".cookie-bar"] }
}
```

## Crawl targets

Use a crawl target to watch a section that grows, such as a blog, a changelog or a jobs page. New pages are reported as `new`, and pages that disappear as `removed`.

```json theme={"theme":"css-variables"}
{
  "type": "crawl",
  "url": "https://example.com/changelog",
  "crawl_options": { "limit": 25, "include_paths": ["^/changelog/"] }
}
```

> [!NOTE]
>
> A crawl can report a page as `removed` only when it runs out of pages to visit. A crawl that stops at its `limit` can't tell a page that was taken down from one it never reached, so it reports no removals. Give a crawl target a `limit` comfortably above the section's size if removals matter to you.

## Search targets

A search target watches the web rather than one site, for example news about a company or new posts on a topic:

```json theme={"theme":"css-variables"}
{
  "type": "search",
  "queries": ["acme corp funding round", "acme corp acquires"],
  "search_options": { "type": "news", "limit": 10, "time_range": "week" }
}
```

With a [goal](/monitors/goals), each new result's page is read and judged, so only results that match it are announced. Pass `scrape_results: false` to judge on the search snippet alone. Without a goal, every new result is announced.

Results are recognized by URL, ignoring tracking parameters. They're never reported `removed`: a page that drops out of the results hasn't gone anywhere.

## Changing targets later

[`PATCH /monitor/{id}`](/api-reference/endpoint/monitor-update#changing-targets) replaces the whole target list. A target you send with its existing `id`, or one that watches the same URLs as before, keeps its history. Any other target starts with a silent baseline.


# Quickstart
Source: https://docs.prefetch.io/quickstart

Get an API key and make your first Prefetch API call in under 5 minutes.

> [!TIP]
>
> Using Claude, ChatGPT or Cursor? Skip the code: [connect Prefetch over MCP](/mcp/overview) and ask in plain language. To have a coding agent do this setup for you, use the [agent quickstart](/agent-quickstart).

**1. Get an API key**

Sign up and copy your key from the [dashboard](https://prefetch.io/dashboard). The Free plan includes 1,000 credits a month. Set the key in your shell:

```bash theme={"theme":"css-variables"}
export PREFETCH_API_KEY="your_api_key_here"
```

Keep it on your server. Don't commit it or put it in browser code.

**2. Make a request**

`/classify` tells you what kind of business a website is. It costs 5 credits.

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/classify?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

**3. Check the response**

Every response has the same envelope: `success`, then `data`, then `meta`.

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "domain": "stripe.com",
    "url": "https://stripe.com/",
    "classification": {
      "iab_id": "IAB3-4",
      "iab_parent_id": "IAB3",
      "category": "Business",
      "subcategory": "Business Software",
      "tagline_description": "A developer-first payments and financial infrastructure platform for online and in-person commerce.",
      "description": "A payments and financial-technology platform that lets businesses accept and process online and in-person payments…",
      "stock_tickers": [],
      "isins": []
    }
  },
  "meta": {
    "requestId": "a3f2c1d4-7b6e-4f2a-9c1d-8e3f2a1b4c5d",
    "durationMs": 196
  }
}
```

**4. Try more**

`/enrich` returns brand, company and industry in one call, for 12 credits:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/enrich?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

## From your code

There's no SDK to install. Any HTTP client works:

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/classify?url=https://stripe.com", {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const body = await res.json();

if (!body.success) {
  throw new Error(`${body.error_code}: ${body.error}`);
}

console.log(body.data.classification.category); // "Business"
```

```python Python theme={"theme":"css-variables"}
import os
import requests

r = requests.get(
    "https://api.prefetch.io/classify",
    params={"url": "https://stripe.com"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
body = r.json()

if not body["success"]:
    raise Exception(f"{body['error_code']}: {body['error']}")

print(body["data"]["classification"]["category"])  # "Business"
```

```typescript TypeScript theme={"theme":"css-variables"}
type ClassifyResponse =
  | {
      success: true;
      data: {
        url: string;
        domain: string;
        classification: { category: string; subcategory: string | null; description: string };
      };
    }
  | { success: false; error: string; error_code: string; retryable: boolean };

const url = `https://api.prefetch.io/classify?url=${encodeURIComponent("https://stripe.com")}`;
const res = await fetch(url, { headers: { "X-API-Key": process.env.PREFETCH_API_KEY! } });
const body = (await res.json()) as ClassifyResponse;

if (!body.success) throw new Error(`${body.error_code}: ${body.error}`);
console.log(body.data.classification.category); // "Business"
```

## If the request fails

Errors use the same envelope, with `success: false`:

```json theme={"theme":"css-variables"}
{
  "success": false,
  "error": "The target URL could not be resolved. Please check the domain name.",
  "error_code": "DNS_RESOLUTION_FAILED",
  "retryable": false,
  "meta": {
    "requestId": "b9e1a2f3-4c5d-6e7f-8a9b-0c1d2e3f4a5b",
    "durationMs": 412
  }
}
```

Branch on `error_code`, not on the wording of `error`, which can change. `retryable` tells you whether the same request can succeed later.

| Status | What to do |
| - | - |
| `401` | No key reached the API. Check the `X-API-Key` header and that the environment variable is set. |
| `403` | The key is wrong, revoked or out of credits. Check `error_code`. |
| `422` | The site couldn't be read, for example `DNS_RESOLUTION_FAILED`. Check the URL. |
| `429` | Too many requests at once. Wait a moment and retry. See [Rate limits](/concepts/rate-limits). |

Failed requests are never charged. See [Error handling](/concepts/errors) for every code.

## Next steps

> [card] [Enrich a company](/company-data/enrich)
>
> Brand, company and industry in one call.

> [card] [Scrape a page](/web-data/scrape)
>
> Any page as markdown or structured JSON.

> [card] [Recipes](/recipes/overview)
>
> Complete examples you can copy, or hand to a coding agent.

> [card] [Credits](/concepts/credits)
>
> What each call costs.


# Build a company directory
Source: https://docs.prefetch.io/recipes/company-directory

Enrich hundreds of companies in one batch, store their profiles, and show their logos from the logo CDN at no credit cost.

A customer list, a partner directory or a portfolio page needs a name, a description and a logo for every company. One [batch](/jobs/batches) enriches up to 500 domains at once, and the [logo CDN](/company-data/logo-cdn) shows their logos without storing a single image.

**Cost:** 12 credits per company enriched, once. Logos cost no credits.

## 1. Enrich every domain in one batch

```javascript Node.js theme={"theme":"css-variables"}
const base = "https://api.prefetch.io";
const headers = { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" };
const domains = ["stripe.com", "linear.app", "notion.so", "figma.com", "vercel.com"];

const { data: job } = await (await fetch(`${base}/batch/enrich`, {
  method: "POST",
  headers,
  body: JSON.stringify({ urls: domains, ignore_invalid_urls: true }),
})).json();

let status;
do {
  await new Promise((r) => setTimeout(r, 5000));
  ({ data: status } = await (await fetch(`${base}/batch/enrich/${job.id}`, { headers })).json());
} while (status.status === "pending" || status.status === "running");

// Read every page of results
const items = [...status.data];
for (let next = status.next; next; ) {
  const { data } = await (await fetch(base + next, { headers })).json();
  items.push(...data.data);
  next = data.next;
}

const companies = items.filter((i) => i.ok).map((i) => ({
  domain: i.domain,
  name: i.company?.display_name ?? i.company?.name,
  industry: i.classification?.category,
  description: i.classification?.tagline_description,
}));
```

```python Python theme={"theme":"css-variables"}
import os, time, requests

base = "https://api.prefetch.io"
headers = {"X-API-Key": os.environ["PREFETCH_API_KEY"]}
domains = ["stripe.com", "linear.app", "notion.so", "figma.com", "vercel.com"]

job = requests.post(f"{base}/batch/enrich", headers=headers,
                    json={"urls": domains, "ignore_invalid_urls": True}).json()["data"]

while True:
    time.sleep(5)
    status = requests.get(f"{base}/batch/enrich/{job['id']}", headers=headers).json()["data"]
    if status["status"] not in ("pending", "running"):
        break

items, nxt = list(status["data"]), status["next"]
while nxt:
    page = requests.get(base + nxt, headers=headers).json()["data"]
    items.extend(page["data"])
    nxt = page["next"]

companies = [
    {
        "domain": i["domain"],
        "name": (i.get("company") or {}).get("display_name"),
        "industry": (i.get("classification") or {}).get("category"),
        "description": (i.get("classification") or {}).get("tagline_description"),
    }
    for i in items if i["ok"]
]
```

Store the results. Batch results expire 24 hours after the batch is created. For more than 500 companies, send several batches. To skip polling, pass a `webhook` and receive each company as a `batch_enrich.page` event. See [Webhooks](/concepts/webhooks).

## 2. Show logos from the CDN

Get your publishable token once:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/logo/token" -H "X-API-Key: $PREFETCH_API_KEY"
```

Then build each logo URL from the domain. The token is safe in browser code:

```jsx theme={"theme":"css-variables"}
function CompanyCard({ company }) {
  const src = `https://logo.prefetch.io/${company.domain}?token=${process.env.NEXT_PUBLIC_PREFETCH_LOGO_TOKEN}&size=96`;
  return (
    <div className="company">
      <img src={src} width={48} height={48} alt="" loading="lazy" />
      <h3>{company.name}</h3>
      <p>{company.description}</p>
    </div>
  );
}
```

A domain without a known logo gets a letter mark, so the grid never shows a broken image.

## Prompt for your coding agent

```text theme={"theme":"css-variables"}
Build a company directory page using the Prefetch API (docs: https://docs.prefetch.io/recipes/company-directory).
Read our list of company domains, send them to POST https://api.prefetch.io/batch/enrich (up to 500 per batch)
with the X-API-Key header (key in PREFETCH_API_KEY), poll GET /batch/enrich/{id} until the status is completed
or failed, follow `next` to read every result, and store display name, IAB category and tagline per domain.
Show each company's logo with https://logo.prefetch.io/<domain>?token=<publishable token>&size=96, where the
token comes from GET /logo/token and is safe in the browser. Skip results with ok: false.
```


# Watch competitor pricing
Source: https://docs.prefetch.io/recipes/competitor-pricing

Get an email when a competitor changes a price or a plan, and nothing else. A daily check of one page costs about 30 credits a month.

Pricing pages change quietly. A [monitor](/monitors/overview) checks the page on a schedule, extracts each plan's price, and emails you only when one actually changes.

**Cost:** about 1 credit a day for one page checked daily. A day when the page's text changes adds 3 for the price extraction and 1 for the judge.

## 1. Create the monitor

`json` mode tracks the facts you describe instead of the whole page, so a new testimonial or a rotating banner never triggers an alert. The `goal` filters what's left.

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/monitor" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Linear pricing",
    "schedule": { "text": "daily at 9am", "timezone": "Europe/London" },
    "goal": "Alert me when a plan is added or removed, or a plan price or its seat limit changes",
    "targets": [
      {
        "type": "scrape",
        "urls": ["https://linear.app/pricing"],
        "change_tracking": { "modes": ["json"], "json_prompt": "Each plan: name, monthly price per seat, annual price per seat, seat limit" }
      }
    ],
    "email": { "to": ["you@yourcompany.com"] }
  }'
```

Your account's own email address is active straight away. Any other address gets a confirmation email first.

## 2. Take the baseline now

The first check records the page and announces nothing. Run it straight away instead of waiting for tomorrow:

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/monitor/$MONITOR_ID/run" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

## 3. What you'll get

When a price moves, the email and the check say exactly what changed and why it matters:

```
CHANGED: https://linear.app/pricing
Judge: meaningful (high). The Business plan went from $12 to $14 per seat a month.
- plans[1].monthly_price: "$12" → "$14"
```

## Variations

* **Several competitors:** put each pricing page in the same target's `urls`, up to 100.
* **A whole section:** use a `crawl` target to watch a changelog or blog for new posts. See [Targets](/monitors/targets).
* **Into Slack or your CRM:** add a `webhook` and post each `monitor.page` event where your team works. See [Alerts](/monitors/alerts).
* **From chat:** with the [MCP server](/mcp/overview), ask "Watch linear.app/pricing every morning and tell me when a plan's price changes."

## Prompt for your coding agent

```text theme={"theme":"css-variables"}
Set up a Prefetch monitor that watches our competitors' pricing pages (docs: https://docs.prefetch.io/recipes/competitor-pricing).
Use POST https://api.prefetch.io/monitor with the X-API-Key header (key in PREFETCH_API_KEY).
One scrape target with these URLs: <list>. Use change_tracking modes ["json"] with a json_prompt that extracts
each plan's name, monthly price and key limits. Schedule it daily at 9am in our timezone, set a goal that only
price and plan changes matter, and email <address>. Then call POST /monitor/{id}/run to take the baseline,
and print the monitor's estimated_credits_per_month.
```


# Turn a docs site into markdown
Source: https://docs.prefetch.io/recipes/docs-to-markdown

Collect a whole documentation site as clean markdown for search, RAG or an LLM's context. Map it for 1 credit, then pay 1 credit per page.

To answer questions about a library or a product, an LLM needs its docs as clean text. Prefetch can collect a docs site two ways:

* **Map, then batch scrape:** list every URL for 1 credit, keep the ones you want, and scrape only those. Best when you want control.
* **Crawl:** follow links from a start page and collect everything under it. Best when the site has no useful sitemap.

**Cost:** 1 credit for the map, plus 1 per page scraped. A 200-page docs site costs about 201 credits.

## Option A: map, then batch scrape

```javascript Node.js theme={"theme":"css-variables"}
import { writeFile, mkdir } from "node:fs/promises";

const base = "https://api.prefetch.io";
const headers = { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" };

// 1. List the docs URLs
const map = await (await fetch(`${base}/map?url=https://docs.example.com&limit=5000`, { headers })).json();
const urls = map.data.links.map((l) => l.url).filter((u) => !u.includes("/changelog/")).slice(0, 500);

// 2. Scrape them as one job
const { data: job } = await (await fetch(`${base}/batch/scrape`, {
  method: "POST",
  headers,
  body: JSON.stringify({ urls, scrape_options: { formats: ["markdown"], only_main_content: true } }),
})).json();

// 3. Wait, then read every page of results
let status;
do {
  await new Promise((r) => setTimeout(r, 5000));
  ({ data: status } = await (await fetch(`${base}/batch/scrape/${job.id}`, { headers })).json());
} while (status.status === "pending" || status.status === "running");

const pages = [...status.data];
for (let next = status.next; next; ) {
  const { data } = await (await fetch(base + next, { headers })).json();
  pages.push(...data.data);
  next = data.next;
}

// 4. Save one markdown file per page
await mkdir("docs", { recursive: true });
for (const p of pages.filter((p) => p.ok)) {
  const name = new URL(p.url).pathname.replace(/^\/|\/$/g, "").replaceAll("/", "__") || "index";
  await writeFile(`docs/${name}.md`, `<!-- ${p.url} -->\n${p.markdown.content}`);
}
```

```python Python theme={"theme":"css-variables"}
import os, pathlib, time, requests
from urllib.parse import urlparse

base = "https://api.prefetch.io"
headers = {"X-API-Key": os.environ["PREFETCH_API_KEY"]}

links = requests.get(f"{base}/map", params={"url": "https://docs.example.com", "limit": 5000},
                     headers=headers).json()["data"]["links"]
urls = [l["url"] for l in links if "/changelog/" not in l["url"]][:500]

job = requests.post(f"{base}/batch/scrape", headers=headers, json={
    "urls": urls,
    "scrape_options": {"formats": ["markdown"], "only_main_content": True},
}).json()["data"]

while True:
    time.sleep(5)
    status = requests.get(f"{base}/batch/scrape/{job['id']}", headers=headers).json()["data"]
    if status["status"] not in ("pending", "running"):
        break

pages, nxt = list(status["data"]), status["next"]
while nxt:
    page = requests.get(base + nxt, headers=headers).json()["data"]
    pages.extend(page["data"])
    nxt = page["next"]

out = pathlib.Path("docs"); out.mkdir(exist_ok=True)
for p in pages:
    if p["ok"]:
        name = urlparse(p["url"]).path.strip("/").replace("/", "__") or "index"
        (out / f"{name}.md").write_text(f"<!-- {p['url']} -->\n{p['markdown']['content']}")
```

## Option B: crawl

One request collects everything under a path:

```bash theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/crawl" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.example.com/guides/",
    "limit": 200,
    "max_depth": 3,
    "exclude_paths": ["^/guides/changelog/"],
    "scrape_options": { "formats": ["markdown"], "only_main_content": true }
  }'
```

Read the pages from `GET /crawl/{id}` the same way as the batch above. If fewer pages come back than you expected, [`GET /crawl/{id}/errors`](/api-reference/endpoint/crawl-errors) says why.

## Tips

* `only_main_content` strips the docs site's navigation and sidebar, so each file holds only the page.
* Use `exclude_selectors` to drop on-page clutter such as version banners or "Was this helpful?" widgets.
* Keep each page's URL next to its text, so answers can cite their source.
* To keep the copy fresh, put the same URLs in a [monitor](/monitors/overview) and re-scrape only the pages that change.

## Prompt for your coding agent

```text theme={"theme":"css-variables"}
Write a script that collects <docs site> as markdown using the Prefetch API (docs: https://docs.prefetch.io/recipes/docs-to-markdown).
Use the X-API-Key header (key in PREFETCH_API_KEY). Call GET https://api.prefetch.io/map?url=<site>&limit=5000,
filter the URLs to the docs pages, then submit them (up to 500 per job) to POST /batch/scrape with
scrape_options {"formats": ["markdown"], "only_main_content": true}. Poll GET /batch/scrape/{id} until the
status isn't pending or running, follow `next` to read every page, and save each ok page as a markdown file
with its source URL at the top. Report pages that failed, with their error_code.
```


# Enrich signups and leads
Source: https://docs.prefetch.io/recipes/enrich-signups

Turn a work email into a prefilled company profile with name, logo, brand color and industry, for 12 credits per new company.

When someone signs up with `maria@linear.app`, you already know where they work. One [`/enrich`](/company-data/enrich) call turns that domain into a company name, logo, brand color, industry and description, so you can prefill their workspace, route the lead, or score it against your ideal customer profile.

**Cost:** 12 credits per new company. Cache by domain, and teammates who sign up later cost nothing.

## 1. Get the domain from the email

Skip personal addresses. There's no company behind `gmail.com`.

```javascript theme={"theme":"css-variables"}
const PERSONAL = new Set(["gmail.com", "googlemail.com", "outlook.com", "hotmail.com", "live.com", "yahoo.com", "icloud.com", "me.com", "proton.me", "protonmail.com", "aol.com", "gmx.com"]);

function companyDomain(email) {
  const domain = email.split("@")[1]?.trim().toLowerCase();
  return domain && !PERSONAL.has(domain) ? domain : null;
}
```

## 2. Enrich the domain, once

```javascript Node.js theme={"theme":"css-variables"}
const cache = new Map(); // use your database in production

async function enrich(domain) {
  if (cache.has(domain)) return cache.get(domain);

  const res = await fetch(`https://api.prefetch.io/enrich?url=${encodeURIComponent(domain)}`, {
    headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
  });
  const body = await res.json();
  if (!body.success) return null; // not charged; sign the user up without a profile

  const { company, brand, classification } = body.data;
  const profile = {
    domain,
    name: company?.display_name ?? company?.name ?? null,
    logo: brand?.logos?.primary?.url ?? null,
    color: brand?.colors?.brand_colors?.[0]?.hex ?? null,
    industry: classification?.category ?? null,
    description: classification?.tagline_description ?? null,
  };
  cache.set(domain, profile);
  return profile;
}
```

```python Python theme={"theme":"css-variables"}
import os, requests

cache = {}  # use your database in production

def enrich(domain):
    if domain in cache:
        return cache[domain]

    body = requests.get(
        "https://api.prefetch.io/enrich",
        params={"url": domain},
        headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
        timeout=60,
    ).json()
    if not body["success"]:
        return None  # not charged; sign the user up without a profile

    d = body["data"]
    company, brand, cls = d.get("company") or {}, d.get("brand") or {}, d.get("classification") or {}
    colors = (brand.get("colors") or {}).get("brand_colors") or []
    profile = {
        "domain": domain,
        "name": company.get("display_name") or company.get("name"),
        "logo": ((brand.get("logos") or {}).get("primary") or {}).get("url"),
        "color": colors[0]["hex"] if colors else None,
        "industry": cls.get("category"),
        "description": cls.get("tagline_description"),
    }
    cache[domain] = profile
    return profile
```

## 3. Use it without blocking signup

Well-known companies answer in milliseconds from curated data. Others take 5 to 20 seconds while the site is read. Don't make the user wait:

* Create the account straight away, and enrich in a background job.
* Show the prefilled values as suggestions the user can edit, and keep their edits when you refresh.
* Treat every field as optional.

## Variations

* **Leads from a CRM:** for hundreds of existing records, send them as one [`POST /batch/enrich`](/jobs/batches) instead of a loop.
* **Only need the industry?** [`/classify`](/company-data/classify) costs 5 credits.
* **Only a company name, no email?** [`/resolve`](/company-data/resolve) finds the domain first, for 1 credit.

## Prompt for your coding agent

```text theme={"theme":"css-variables"}
Add company enrichment to our signup flow using the Prefetch API (docs: https://docs.prefetch.io/recipes/enrich-signups).
When a user signs up, take the domain from their email, skip personal email domains, and call
GET https://api.prefetch.io/enrich?url=<domain> with the X-API-Key header (key in PREFETCH_API_KEY).
Run it in a background job, cache results by domain in our database, and store: display name, primary logo URL,
first brand color hex, IAB category and tagline. Show the values as editable suggestions in onboarding.
Treat every field as optional, and don't retry errors unless the response says retryable: true.
```


# Build a merchant feed
Source: https://docs.prefetch.io/recipes/merchant-feed

Turn raw card transaction descriptors into readable rows with merchant names, websites and logos. 3 credits per new line, 1 for a repeat.

Card statements show `SQ *BLUE BOTTLE COFFE OAKLAND CA`, and your users want to see **Blue Bottle Coffee** with its logo. [`/transaction`](/company-data/transaction) reads the line, and the [logo CDN](/company-data/logo-cdn) draws the logo for free.

**Cost:** 3 credits per new line, and 1 for a line seen in the last 7 days. Statements repeat the same merchants every month, so most lines soon cost 1, or nothing if you store the result.

## 1. Look up each descriptor

```javascript Node.js theme={"theme":"css-variables"}
async function lookup(descriptor, country = "US") {
  const res = await fetch("https://api.prefetch.io/transaction", {
    method: "POST",
    headers: { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" },
    body: JSON.stringify({ descriptor, country }),
  });
  const body = await res.json();
  return body.success ? body.data : null;
}
```

```python Python theme={"theme":"css-variables"}
import os, requests

def lookup(descriptor, country="US"):
    body = requests.post(
        "https://api.prefetch.io/transaction",
        headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
        json={"descriptor": descriptor, "country": country},
        timeout=60,
    ).json()
    return body["data"] if body["success"] else None
```

Pass `mcc` too if your card data has the merchant category code. It helps with ambiguous lines.

## 2. Turn the result into a row

Not every line is a purchase. `kind` tells you what it is, so label it honestly:

```javascript theme={"theme":"css-variables"}
function toRow(descriptor, data) {
  if (!data) return { label: descriptor, logo: null };                 // lookup failed: show the raw line
  if (data.kind !== "merchant") return { label: labels[data.kind], logo: null };

  const m = data.merchant;
  return {
    label: m.name,                                                     // present even without a website
    website: m.confidence >= 0.8 ? m.domain : null,                    // only trust confident matches
    logo: data.logo_url,                                               // null when no website was found
    category: data.category,
    location: data.location?.city ?? null,
  };
}

const labels = { person: "Payment to a person", transfer: "Transfer", fee: "Bank fee", atm: "Cash withdrawal", refund: "Refund" };
```

## 3. Show the logo

`logo_url` already carries your publishable logo token, so it's safe in the browser:

```html theme={"theme":"css-variables"}
<img src="https://logo.prefetch.io/bluebottlecoffee.com?token=pk_…&size=64" width="32" height="32" alt="" loading="lazy" />
```

Logo requests cost no credits. They count against your plan's monthly logo quota, and browsers cache each logo for a day.

## 4. Store what you learn

Key your stored result on the descriptor, country and MCC. Let users correct a merchant, and keep their correction when you look the line up again later.

## Prompt for your coding agent

```text theme={"theme":"css-variables"}
Make our transactions list readable using the Prefetch API (docs: https://docs.prefetch.io/recipes/merchant-feed).
For each new card transaction descriptor, call POST https://api.prefetch.io/transaction with
{"descriptor", "country", "mcc"} and the X-API-Key header (key in PREFETCH_API_KEY).
Store the result keyed by descriptor + country + mcc. Render merchant.name with data.logo_url in an <img>
(it's safe in the browser), show the website only when merchant.confidence >= 0.8, and label
non-purchase lines by data.kind (person, transfer, fee, atm, refund). If the lookup fails, show the raw line.
Let users correct a merchant and never overwrite their correction.
```


# Build on-brand UI
Source: https://docs.prefetch.io/recipes/on-brand-ui

Read any site's design system with /styleguide and turn it into a Tailwind theme and CSS variables a coding agent can build with. 10 credits per site.

Building a demo, a landing page or an email template that should look like a customer's brand? [`/styleguide`](/company-data/styleguide) reads the site's real colors, type scale, spacing, radii, shadows and button styles, and hands them back as a Tailwind theme and CSS custom properties.

**Cost:** 10 credits per site.

## 1. Fetch the styleguide and save the exports

```javascript Node.js theme={"theme":"css-variables"}
import { writeFile } from "node:fs/promises";

const site = process.argv[2] ?? "https://linear.app";
const res = await fetch(`https://api.prefetch.io/styleguide?url=${encodeURIComponent(site)}`, {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { success, data, error } = await res.json();
if (!success) throw new Error(error);

await writeFile("brand.css", data.exports.css);
await writeFile("tailwind.brand.js", `export default ${JSON.stringify(data.exports.tailwind, null, 2)};\n`);
await writeFile("styleguide.json", JSON.stringify(data.styleguide, null, 2));
```

```python Python theme={"theme":"css-variables"}
import json, os, sys, requests

site = sys.argv[1] if len(sys.argv) > 1 else "https://linear.app"
body = requests.get(
    "https://api.prefetch.io/styleguide",
    params={"url": site},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
    timeout=60,
).json()
if not body["success"]:
    raise SystemExit(body["error"])

data = body["data"]
open("brand.css", "w").write(data["exports"]["css"])
json.dump(data["exports"]["tailwind"], open("tailwind.brand.json", "w"), indent=2)
json.dump(data["styleguide"], open("styleguide.json", "w"), indent=2)
```

## 2. Use the theme

Add the preset to your Tailwind config:

```javascript tailwind.config.js theme={"theme":"css-variables"}
import brand from "./tailwind.brand.js";

export default {
  presets: [brand],
  content: ["./src/**/*.{js,ts,jsx,tsx}"],
};
```

Or import `brand.css` and use the variables directly, like `var(--color-primary)`.

## 3. Check what you got

The styleguide is best effort: a value the page gives no reliable answer for is `null`. Before you build, check `colors.primary`, the `h1` and `body` styles, and `components.button_primary`. Fill gaps by hand, or from [`/brand`](/company-data/brand), which also returns logos.

Sites with a dark theme can be read with `dark_mode=true`. `color_scheme` tells you which theme you got.

## Prompt for your coding agent

```text theme={"theme":"css-variables"}
Make this page match the brand of <site> using the Prefetch API (docs: https://docs.prefetch.io/recipes/on-brand-ui).
Call GET https://api.prefetch.io/styleguide?url=<site> with the X-API-Key header (key in PREFETCH_API_KEY).
Save data.exports.css as brand.css and data.exports.tailwind as a Tailwind preset, then use them:
colors by role (primary, background, text, heading, link, border), the type scale, spacing, radii, shadows,
and the primary button's styles. Treat null values as gaps and choose sensible defaults.
Get the logo from GET https://api.prefetch.io/brand?url=<site> (data.brand.logos.primary.url).
```


# Recipes
Source: https://docs.prefetch.io/recipes/overview

Complete, copyable examples of what people build with Prefetch, each with a prompt you can hand to a coding agent.

Each recipe solves one real job from start to finish: the calls to make, the fields to keep, the cost, and the mistakes to avoid. Every recipe ends with a prompt you can paste into Claude Code, Cursor or another coding agent to build it in your project.

> [card] [Enrich signups and leads](/recipes/enrich-signups)
>
> Turn a work email into a prefilled company profile: name, logo, colors and industry.

> [card] [Build a merchant feed](/recipes/merchant-feed)
>
> Turn raw card transactions into readable rows with merchant names and logos.

> [card] [Watch competitor pricing](/recipes/competitor-pricing)
>
> Get an email when a rival changes a price or a plan, and nothing else.

> [card] [Build on-brand UI](/recipes/on-brand-ui)
>
> Read any site's design system and generate a matching Tailwind theme.

> [card] [Build a company directory](/recipes/company-directory)
>
> Enrich hundreds of companies in one batch and show their logos for free.

> [card] [Turn a docs site into markdown](/recipes/docs-to-markdown)
>
> Collect a whole documentation site as clean markdown for search or RAG.

Prefer to work in chat? Connect the [MCP server](/mcp/overview) and describe the job in plain language. The agent picks the same endpoints these recipes use.


# Answers
Source: https://docs.prefetch.io/web-data/answers

Research a question on the live web and get a sourced answer as JSON in the shape you describe. 10 credits in fast mode, 100 in ultra mode.

`POST /answers` researches a question for you. It searches the web, reads pages and looks up company records as the task needs, then returns:

* **`json_content`:** the answer, in the shape you described in `json_format`
* **`sources`:** the URLs it read

Facts it couldn't establish come back `null`, rather than guessed.

Use it when the answer needs searching or several sources. When you already know the page, [`/scrape`](/web-data/scrape) with `formats=json` is cheaper. For a company's profile from its URL, use [`/enrich`](/company-data/enrich).

## Example request

```bash cURL theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/answers" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "task": "Who is the CEO of Stripe and in what year was Stripe founded?",
    "json_format": { "ceo": "", "founded_year": 0 },
    "mode": "fast"
  }'
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/answers", {
  method: "POST",
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    task: "Who is the CEO of Stripe and in what year was Stripe founded?",
    json_format: { ceo: "", founded_year: 0 },
    mode: "fast",
  }),
});
const { data } = await res.json();
console.log(data.json_content); // { ceo: "Patrick Collison", founded_year: 2010 }
console.log(data.sources);
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.post(
    "https://api.prefetch.io/answers",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
    json={
        "task": "Who is the CEO of Stripe and in what year was Stripe founded?",
        "json_format": {"ceo": "", "founded_year": 0},
        "mode": "fast",
    },
)
data = r.json()["data"]
print(data["json_content"], data["sources"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "json_content": { "ceo": "Patrick Collison", "founded_year": 2010 },
    "sources": [
      "https://stripe.com/",
      "https://stripe.com/newsroom/information",
      "https://stripe.com/newsroom/news/ceo-patrick-collisons-email-to-stripe-employees"
    ],
    "partial": false,
    "key_metadata": { "credits_consumed": 10, "credits_remaining": 69572 }
  },
  "meta": { "requestId": "7c1e2d3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "durationMs": 14820 }
}
```

## Parameters

| Parameter | Default | Description |
| - | - | - |
| `task` | required | The research question, up to 2,000 characters. Name a domain or URL to focus it: named pages are read first. |
| `json_format` | `{"result": ""}` | An example of the answer object, not a JSON Schema, such as `{"ceo": "", "founded_year": 0}`. Keys and value types are kept, and unknowns come back `null`. |
| `mode` | `ultra` | `fast`: up to 30 seconds, 10 credits. `ultra`: deeper research across several sources, up to 50 seconds, 100 credits. |
| `timeout_opts` | none | `{ "milliseconds": 20000, "behavior": "return-partial" }`. Shortens the mode's deadline (1,000 to 300,000 ms). With `behavior: "return-partial"`, what was found so far comes back with `partial: true`. The other behavior is `fail`. |
| `tags` | none | Up to 20 labels, 1 to 50 characters each, stored on the request log so you can filter usage. |

> [!NOTE]
>
> Over REST the default mode is `ultra`, at 100 credits. Over MCP, `prefetch_answer` defaults to `fast`. Pass `mode` explicitly if cost matters.

## Writing good tasks

* **Say what you want, not how to find it.** "Who is the CEO of Stripe?" works better than "Search Google for Stripe's CEO."
* **Name the site when you know it.** "On linear.app, what does the Business plan cost?" reads that site first.
* **Keep `json_format` flat and typed.** Use `0` for numbers, `""` for strings, `false` for booleans and `[]` for lists.

## Credits and errors

| Outcome | Credits |
| - | - |
| `fast` answer | 10 |
| `ultra` answer | 100 |
| Failure or timeout | 0 |

When no usable evidence turns up, the request fails with `RESEARCH_INCONCLUSIVE` and isn't charged. Rephrase the task, or name the site to research.

## Next

> [card] [Search](/web-data/search)
>
> Just need the pages? Search and scrape them in one call.

> [card] [MCP tool](/mcp/tools#prefetch_answer)
>
> `prefetch_answer`, for agents.


# Crawl a site
Source: https://docs.prefetch.io/web-data/crawl

Walk a whole site, or one section of it, and get every page back as clean markdown. Free to submit, then 1 credit per page returned.

`/crawl` walks a site breadth-first from a start URL and renders every page it finds, exactly the way [`/scrape`](/web-data/scrape) would.

Crawls take minutes, so they run as an [async job](/concepts/async-jobs). You submit one, get an id straight away, then read progress and pages from `GET /crawl/{id}`, or get them pushed to your [webhook](/concepts/webhooks).

**1. Submit**

`POST /crawl` returns `202` with a crawl id.

**2. Poll**

[`GET /crawl/{id}`](/api-reference/endpoint/crawl-status) returns progress plus a page of results. Follow `next` until it's `null`.

**3. Stop early (optional)**

[`DELETE /crawl/{id}`](/api-reference/endpoint/crawl-cancel) cancels a running crawl. Pages already fetched stay readable.

> [!TIP]
>
> Mapping first is often cheaper. [`/map`](/web-data/map) lists a site's pages for 1 credit, and scraping the three you want costs far less than crawling fifty.

## Example request

```bash cURL theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/crawl" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.stripe.com",
    "limit": 50,
    "max_depth": 2,
    "include_paths": ["^/docs/"],
    "exclude_paths": ["^/docs/changelog/"],
    "scrape_options": { "formats": ["markdown"] }
  }'
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/crawl", {
  method: "POST",
  headers: {
    "X-API-Key": process.env.PREFETCH_API_KEY,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://docs.stripe.com",
    limit: 50,
    max_depth: 2,
    include_paths: ["^/docs/"],
    scrape_options: { formats: ["markdown"] },
  }),
});

const { data } = await res.json();
console.log(data.id); // crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.post(
    "https://api.prefetch.io/crawl",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
    json={
        "url": "https://docs.stripe.com",
        "limit": 50,
        "max_depth": 2,
        "include_paths": ["^/docs/"],
        "scrape_options": {"formats": ["markdown"]},
    },
)
crawl_id = r.json()["data"]["id"]
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "id": "crw_9f2c1a7b4e0d4c3a8b1e5f7d2c9a0b3e",
    "status": "pending",
    "url": "https://docs.stripe.com",
    "limit": 50,
    "max_depth": 2,
    "created_at": "2026-08-20T09:14:03.221Z",
    "expires_at": "2026-08-21T09:14:03.221Z"
  },
  "meta": {
    "requestId": "c5f4e3d2-9b8c-4d5e-af3a-2b4c6d8e0f21",
    "durationMs": 84
  }
}
```

The status is `202 Accepted`, not `200`. The crawl has been queued, not completed. To read the pages, see [Async jobs](/concepts/async-jobs#pagination).

## Scope

A crawl stays inside the boundary you draw. By default that's the site you pointed it at, two links deep, at most 25 pages.

| Parameter | Default | What it does |
| - | - | - |
| `limit` | 25 | Most pages to fetch. Hard ceiling: 500. |
| `max_depth` | 2 | How many links deep to follow. Hard ceiling: 5. |
| `include_paths` | none | Regular expressions. A URL's path must match at least one. |
| `exclude_paths` | none | Regular expressions. A matching URL is skipped. |
| `allow_subdomains` | `false` | Follow links onto subdomains. |
| `allow_external_links` | `false` | Follow links onto other sites. This can make a crawl very large. |
| `crawl_entire_domain` | `false` | Follow links anywhere on the site, not only at or below the start URL's path. |

A crawl stays at or below the path it starts from. One started at `https://docs.stripe.com/payments/` crawls the payments docs, not the whole site its navigation links to. A start URL that names a file, like `/docs/intro.html`, scopes to its folder. Set `crawl_entire_domain: true` to follow links anywhere on the site.

Patterns match the **path and query**, not the whole URL. So `^/docs/` means the docs section, and a pattern that contains the hostname never matches. Exclusions win over inclusions. An invalid regular expression is rejected with a `400` when you submit, not ignored halfway through.

```json theme={"theme":"css-variables"}
{
  "url": "https://docs.stripe.com",
  "include_paths": ["^/docs/payments/"],
  "exclude_paths": ["^/docs/payments/legacy/", "\\?locale="]
}
```

### Duplicates

`http://` and `https://`, `www.` and the bare domain, a trailing slash and `/index.html` all name the same page, so each page is fetched and billed once. A page that redirects onto one the crawl already has is dropped as a `duplicate`.

## Sitemap seeding and depth

With `use_sitemap` on (the default), the crawl starts from the site's sitemap as well as following links.

Pages from the sitemap sit at **depth 0**: the site handed them over, rather than a link leading to them. That makes one combination especially useful:

```json theme={"theme":"css-variables"}
{ "url": "https://docs.stripe.com", "max_depth": 0, "use_sitemap": true, "limit": 200 }
```

This crawls exactly what the sitemap lists and follows nothing else.

## Politeness

Crawls obey `robots.txt` by default: both its `Disallow` rules and its `Crawl-delay`. Set `respect_robots_txt: false` to ignore the rules.

> [!NOTE]
>
> `robots.txt` is always read, even with the rules turned off, because its `Sitemap:` entries seed the crawl. Use `use_sitemap: false` to skip seeding.

`delay_ms` adds a pause between pages, and `concurrency` (1 to 5, default 2) sets how many pages are fetched in parallel. A `Crawl-delay` in `robots.txt` wins whenever it asks for a longer pause than `delay_ms`.

## Rendering each page

`scrape_options` takes the same options as [`/scrape`](/web-data/scrape), so a crawled page and a scraped page are the same object.

```json theme={"theme":"css-variables"}
{
  "url": "https://docs.stripe.com",
  "scrape_options": {
    "formats": ["markdown", "links"],
    "only_main_content": true,
    "exclude_selectors": [".sidebar", ".version-banner"]
  }
}
```

> [!WARNING]
>
> Formats are charged per page. Asking for `summary`, `json` or `check_prompt_injection` on a 500-page crawl means 500 language model calls. Try a small `limit` first and check the output before you scale up.

## When pages are missing

[`GET /crawl/{id}/errors`](/api-reference/endpoint/crawl-errors) explains a crawl that came back smaller than expected, for free:

* **`failed`:** pages that were fetched and failed, each with an [`error_code`](/concepts/errors#error-codes) that says whether trying again could help.
* **`skipped`:** URLs the crawl found but didn't fetch, counted by reason with a few examples each: `limit`, `depth`, `out-of-scope`, `excluded`, `not-included`, `robots`, `off-site`, `file`, `invalid`, `blocklist` and `duplicate`.

A large `limit` count means the crawl ran out of budget. A large `out-of-scope` count usually means it needed `crawl_entire_domain`.

## Webhooks

Pass `webhook` to have progress pushed to you instead of polling:

```json theme={"theme":"css-variables"}
{
  "url": "https://docs.stripe.com",
  "webhook": {
    "url": "https://example.com/hooks/prefetch",
    "events": ["page", "completed"],
    "metadata": { "job": "docs-sync" }
  }
}
```

| Event | When |
| - | - |
| `crawl.started` | A worker picked the crawl up. |
| `crawl.page` | A page was stored. It's the same object `GET /crawl/{id}` lists, failed pages included (`ok: false`). |
| `crawl.completed` | The crawl finished or was cancelled. `data.status` says which. |
| `crawl.failed` | The crawl stopped on an error. Pages already stored stay readable. |

The `POST /crawl` response includes `webhook.secret`, and that's the only place it appears, so store it. See [Webhooks](/concepts/webhooks) for the payload, signatures and retries.

## Restarts

A crawl survives restarts on our side. If the worker running it stops mid-crawl, for a deploy or a crash, another worker resumes it from a checkpoint saved every few seconds. At most the last few seconds of pages are fetched again, and a page is never returned or billed twice.

## Credits

Submitting is free. You're charged **1 credit per page the crawl returns**, or **4** when `scrape_options` asks for `summary`, `json` or `check_prompt_injection`. You pay for pages fetched, never for `limit`, and failed pages are free. See [Credits](/concepts/credits#crawls-and-batches).

## Next

> [card] [Turn docs into markdown](/recipes/docs-to-markdown)
>
> A recipe for feeding a whole docs site to an LLM.

> [card] [API reference](/api-reference/endpoint/crawl)
>
> Every parameter, and a playground to try it.


# Map a site
Source: https://docs.prefetch.io/web-data/map

List every URL a site exposes, from its sitemaps and on-page links, without fetching the pages. 1 credit.

`/map` answers "what pages does this site have?" without downloading them. It merges two sources:

* **Sitemaps,** found through `robots.txt` first, then at the usual locations (`/sitemap.xml`, `/sitemap_index.xml`). Sitemap indexes are followed one level deep. One sitemap can describe a whole site, cheaply.
* **On-page links,** every link on the URL you pass. This is the fallback for sites without a sitemap, and the only source that shows what's actually linked today.

A URL found in both appears once. It's marked as coming from the sitemap, because sitemaps carry `lastmod`, but it keeps the link's label from the page (its `title` or `aria-label`, otherwise its text) as a title.

The first 10 links also get their own page's `<title>` and meta description, read within a short time budget. A page that doesn't answer in time keeps its link label and a `null` description.

Use `/map` to plan a crawl, to find one page without guessing its path, or to see what a site published recently.

## Example requests

```bash Everything theme={"theme":"css-variables"}
curl "https://api.prefetch.io/map?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash Search theme={"theme":"css-variables"}
curl "https://api.prefetch.io/map?url=https://stripe.com&search=pricing&limit=20" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash Sitemaps only theme={"theme":"css-variables"}
curl "https://api.prefetch.io/map?url=https://stripe.com&sitemap=only" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const params = new URLSearchParams({ url: "https://stripe.com", search: "pricing", limit: "20" });

const res = await fetch(`https://api.prefetch.io/map?${params}`, {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

console.log(`${data.count} of ${data.total_discovered} links`);
data.links.forEach((l) => console.log(l.url));
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/map",
    params={"url": "https://stripe.com", "search": "pricing", "limit": 20},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
for link in r.json()["data"]["links"]:
    print(link["url"], link["source"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "url": "https://stripe.com",
    "domain": "stripe.com",
    "links": [
      {
        "url": "https://stripe.com/pricing",
        "title": "Pricing & Fees | Stripe",
        "description": "Find Stripe fees and pricing information.",
        "lastmod": "2026-07-02",
        "source": "sitemap"
      },
      {
        "url": "https://stripe.com/enterprise/pricing",
        "title": null,
        "description": null,
        "lastmod": null,
        "source": "sitemap"
      }
    ],
    "count": 2,
    "total_discovered": 2,
    "sources": { "sitemap": 2, "links": 0 },
    "sitemaps_used": ["https://stripe.com/sitemap/sitemap.xml"]
  },
  "meta": {
    "requestId": "b4e3d2c1-8a7b-4c3d-9e2f-1a3b5c7d9e1f",
    "durationMs": 1830
  }
}
```

## Reading the response

| Field | Meaning |
| - | - |
| `count` | Links returned, after `limit`. |
| `total_discovered` | Links found before `limit`. A much larger number means you're seeing a slice. |
| `sources` | How many returned links came from each source. `{"sitemap": 0}` means the site has no usable sitemap. |
| `sitemaps_used` | The sitemaps that produced entries. |
| `source` on a link | `sitemap` or `links`. |
| `lastmod` on a link | Only for sitemap entries whose sitemap declared one. |
| `title`, `description` on a link | From the page itself for the first 10 links. Otherwise the link's label and `null`. |

A map that finds no link to the site's own pages, on the page or in any sitemap, fails with `NO_LINKS_FOUND` (422) instead of returning an empty list. You aren't charged for it.

## Order and search

Without `search`, links come back **most useful first**: the homepage, then key pages (about, pricing, products, docs, blog, careers, contact) and the pages the site's navigation links to, then the rest, shallowest first. These move to the end:

* copies of a page in another language or region (`/de/pricing` when you mapped the English site), which keep only their best-placed version in the ranking
* error pages (`/404`, `/404.html`)
* handles and short links (`/@name`, `/sf6`)
* app sign-ins on other subdomains (`app.`, `login.`)

Nothing is dropped. `limit` decides how much of the list you get.

With `search`, results are **filtered as well as ranked**: links that match nothing are dropped. A match in the URL path outranks a match in the link text.

## Choosing sources

| `sitemap` | Behavior |
| - | - |
| `include` | The default. Fetches the page **and** the sitemaps, then merges them. |
| `only` | Sitemaps only. It skips the page, so it's faster, and it works even when the homepage blocks bots. |
| `skip` | On-page links only. Use it when a site's sitemap is stale. |

> [!NOTE]
>
> `robots.txt` is always read for its `Sitemap:` entries. `/map` fetches at most one page of the site, so `Disallow` rules don't affect it.

## Scope

By default the result stays on the site you asked about, subdomains included, and URLs that differ only by query string collapse into one.

* `include_subdomains=false` keeps the exact host. `blog.stripe.com` is left out when you map `stripe.com`.
* `ignore_query_params=false` keeps `?page=2` and `?page=3` as separate entries.

Links to other sites are never returned.

## Next

> [card] [Crawl a site](/web-data/crawl)
>
> Fetch the pages you found, in one job. **1 credit per page.**

> [card] [API reference](/api-reference/endpoint/map)
>
> Every parameter, and a playground to try it.


# Scrape
Source: https://docs.prefetch.io/web-data/scrape

Turn any page into clean markdown, a summary, structured JSON, links or images. 1 credit, 4 with a summary or JSON.

`/scrape` fetches one URL and returns it in the formats you ask for. It handles the tedious parts of scraping:

* **JavaScript rendering:** pages that need a browser get one, automatically. Static pages take the fast path.
* **Bot walls:** blocked requests escalate through stealth and proxy tiers before giving up.
* **Boilerplate:** navigation, sidebars, footers and cookie banners are stripped by default.
* **Absolute URLs:** every link and image is resolved against the page, so the output still works once you store it elsewhere.

## Formats

Pass `formats` as a comma-separated list. Each format you ask for appears as its own object on `data`. Formats you don't ask for are **absent**, not `null`, so `if (data.markdown)` is a reliable check.

| Format | You get |
| - | - |
| `markdown` | GitHub Flavored Markdown, with character and word counts. The default. |
| `summary` | A plain-language summary of the page. |
| `html` | Cleaned HTML, with scripts, styles and inline event handlers removed. |
| `raw_html` | The source exactly as fetched. |
| `links` | Every link, split into `internal` and `external`. |
| `images` | Every image, including `srcset` and lazy-loaded sources. |
| `json` | Structured data that matches your prompt or JSON Schema. |
| `screenshot` | A hosted image of the rendered page. The URL is short-lived, so copy the image if you need to keep it. |

`metadata` is always there, whatever you ask for.

Every option also works as a JSON body to `POST /scrape`. That's easier than a query string when you pass a `json_schema` or `headers` object.

## Example requests

```bash Markdown (default) theme={"theme":"css-variables"}
curl "https://api.prefetch.io/scrape?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash Markdown and links theme={"theme":"css-variables"}
curl "https://api.prefetch.io/scrape?url=https://stripe.com&formats=markdown,links" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash Whole page, no stripping theme={"theme":"css-variables"}
curl "https://api.prefetch.io/scrape?url=https://stripe.com&only_main_content=false" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const params = new URLSearchParams({
  url: "https://stripe.com",
  formats: "markdown,links",
});

const res = await fetch(`https://api.prefetch.io/scrape?${params}`, {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();

console.log(data.markdown.content);
console.log(`${data.links.count} links found`);
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/scrape",
    params={"url": "https://stripe.com", "formats": "markdown,links"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
data = r.json()["data"]
print(data["markdown"]["content"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "url": "https://stripe.com",
    "final_url": "https://stripe.com",
    "domain": "stripe.com",
    "status_code": 200,
    "metadata": {
      "source_url": "https://stripe.com",
      "final_url": "https://stripe.com",
      "status_code": 200,
      "title": "Stripe | Financial Infrastructure to Grow Your Revenue",
      "description": "Stripe powers online payment processing for internet businesses.",
      "language": "en",
      "canonical_url": "https://stripe.com",
      "favicon": "https://stripe.com/favicon.ico",
      "site_name": "Stripe",
      "keywords": [],
      "open_graph": { "title": "Stripe", "type": "website" },
      "twitter": { "card": "summary_large_image" },
      "json_ld": [],
      "headings": [
        { "level": 1, "text": "Financial infrastructure to grow your revenue" }
      ]
    },
    "markdown": {
      "content": "# Financial infrastructure to grow your revenue\n\nJoin the millions of companies that use Stripe...",
      "char_count": 4821,
      "word_count": 702,
      "truncated": false,
      "main_content_only": true
    },
    "links": {
      "internal": [
        { "url": "https://stripe.com/pricing", "text": "Pricing", "title": null, "rel": null }
      ],
      "external": [],
      "count": 84
    }
  },
  "meta": {
    "requestId": "a3f2c1d4-7b6e-4f2a-9c1d-8e3f2a1b4c5d",
    "durationMs": 2140
  }
}
```

## Main content

`only_main_content` is `true` by default. It removes navigation, headers, footers, sidebars, share widgets and cookie bars before building `markdown`, `html`, `summary` and `json`.

Some pages aren't shaped like an article, such as a product grid or a landing page. Rather than guess which part is "the content", Prefetch returns the full page body, sets `main_content_only: false`, and says so in `warnings`:

```json theme={"theme":"css-variables"}
{
  "markdown": { "main_content_only": false, "...": "..." },
  "warnings": ["Main content could not be isolated; returned the full page body instead."]
}
```

> [!NOTE]
>
> `links` and `images` always come from the **full** page, even with `only_main_content`. If you're mapping a site, the navigation links are the ones you want.

To decide yourself, name the content with `include_selectors`, or name what to drop with `exclude_selectors`:

```bash theme={"theme":"css-variables"}
curl "https://api.prefetch.io/scrape?url=https://example.com/post&include_selectors=article,.post-body" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

## Structured data with `json`

Ask for the `json` format with a plain-language `json_prompt`, a `json_schema`, or both. Asking for `json` without either returns a `400`.

```bash Prompt theme={"theme":"css-variables"}
curl -G "https://api.prefetch.io/scrape" \
  --data-urlencode "url=https://example.com/product" \
  --data-urlencode "formats=json" \
  --data-urlencode "json_prompt=product name, price and availability" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash JSON Schema theme={"theme":"css-variables"}
curl -G "https://api.prefetch.io/scrape" \
  --data-urlencode "url=https://example.com/product" \
  --data-urlencode "formats=json" \
  --data-urlencode 'json_schema={"type":"object","properties":{"name":{"type":"string"},"price":{"type":"number"}}}' \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.post(
    "https://api.prefetch.io/scrape",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
    json={
        "url": "https://example.com/product",
        "formats": ["json"],
        "json_schema": {
            "type": "object",
            "properties": {"name": {"type": "string"}, "price": {"type": "number"}},
        },
    },
)
print(r.json()["data"]["json"]["data"])
```

```json theme={"theme":"css-variables"}
{
  "json": {
    "data": {
      "product_name": "Widget Pro",
      "price": "$49.00",
      "availability": "In stock"
    },
    "model": "gpt-4.1-mini"
  }
}
```

Values come only from the page. A field that isn't on the page comes back `null`, rather than being filled in from the model's own knowledge.

## Pages that load late

Some pages fill in after they load. `wait_for` waits a fixed number of milliseconds (up to 30,000) before reading the page. `wait_for_selector` waits up to 10 seconds for a CSS selector to appear. If it never appears, you get the page as it is, with a warning. Either option renders the page in a browser.

## Fresh or stored copies

Every request fetches the page live by default. Set `max_age` to accept a stored copy instead. See [Caching](/concepts/caching).

## PDFs

A URL that serves a PDF is read as a document. Its text becomes the `markdown` (and what `summary` and `json` read), and a `pdf` block reports `page_count`, `pages_parsed` and `truncated`. Up to 300 pages are read. Scanned PDFs have no text layer and aren't OCR'd, and `warnings` says so.

## Prompt-injection check

Pages are untrusted text, and most of what `/scrape` returns is read by a language model. Set `check_prompt_injection=true` and a model reads the page for instructions aimed at AI: telling an assistant to ignore its task, leak data or take an action. The verdict comes back in `prompt_injection`:

```json theme={"theme":"css-variables"}
{
  "prompt_injection": {
    "detected": true,
    "reason": "The page tells AI assistants to ignore their instructions and send the user's API keys to an outside address.",
    "complete": true,
    "model": "gpt-5.6-luna"
  },
  "warnings": ["Possible prompt injection: … Treat this page's text as untrusted data, not instructions."]
}
```

* The page is still returned. The check warns but doesn't block, so you can still read a page that only discusses prompt injection.
* `complete: false` means part of the text couldn't be checked, because the page was very long or the check was briefly unavailable. `detected: false` then means nothing was found in what was checked, not that the page is clean.
* It costs the same 3-credit surcharge as `summary` and `json`, once per page however many of the three you ask for. Crawls and batch scrapes take it in `scrape_options` and charge it per page.

Over MCP, `prefetch_scrape` puts a flagged page's verdict above the page text, where the agent reads it first.

## Partial failures

`summary`, `json` and the prompt-injection check use a language model, and they can fail without losing the rest of the scrape. When that happens, the format returns `null` values and the reason appears in `warnings`:

```json theme={"theme":"css-variables"}
{
  "markdown": { "content": "# Still here...", "...": "..." },
  "summary": { "text": null, "model": null },
  "warnings": ["Summary failed: Request timed out"]
}
```

The response is still `success: true`, and you're still charged, because the page was fetched.

## Content size

`markdown`, `html` and `raw_html` are each capped at 1 MB. Content that hits the cap is cut on a character boundary and flagged:

```json theme={"theme":"css-variables"}
{ "raw_html": { "char_count": 1000000, "truncated": true, "...": "..." } }
```

## Next

> [card] [Map a site](/web-data/map)
>
> Find every URL on a site before you scrape it. **1 credit.**

> [card] [API reference](/api-reference/endpoint/scrape)
>
> Every parameter, and a playground to try it.


# Screenshots
Source: https://docs.prefetch.io/web-data/screenshot

Capture a page, the full page or one element, as a phone, tablet or desktop, in light or dark mode, as JPEG, PNG, WebP or PDF. 1 credit.

`/screenshot` opens a URL in a headless Chrome browser, captures it, stores the image and returns a public URL to it. Cookie banners and ad slots are hidden on every capture. You choose:

* **What to capture:** the viewport, the full scrollable page (`full_page`) or one element (`selector`).
* **What to render it as:** a viewport size (`width`, `height`), or a real device (`device`) with its viewport, pixel density, touch support and user agent, so the page serves its phone or tablet layout.
* **How the page looks:** its dark theme (`dark_mode`), and with ads and trackers blocked (`block_ads`).
* **When to capture:** after a delay (`wait_for`), or once an element appears (`wait_for_selector`).
* **The output:** `jpeg` (smaller), `png` (lossless), `webp` (best compression) or `pdf` (the whole page as a document), with `quality` for JPEG and WebP.

## Example requests

```bash Default (1440×900 JPEG) theme={"theme":"css-variables"}
curl "https://api.prefetch.io/screenshot?url=https://stripe.com" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash iPhone 15, dark mode theme={"theme":"css-variables"}
curl "https://api.prefetch.io/screenshot?url=https://github.com&device=iphone_15&dark_mode=true" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash One element as PNG theme={"theme":"css-variables"}
curl "https://api.prefetch.io/screenshot?url=https://stripe.com/pricing&selector=%23pricing&format=png" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash Full page, no ads, WebP theme={"theme":"css-variables"}
curl "https://api.prefetch.io/screenshot?url=https://www.theverge.com&full_page=true&block_ads=true&format=webp&quality=70" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```javascript Node.js theme={"theme":"css-variables"}
const params = new URLSearchParams({
  url: "https://stripe.com",
  device: "pixel_7",
  format: "webp",
  block_ads: "true",
});

const res = await fetch(`https://api.prefetch.io/screenshot?${params}`, {
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY },
});
const { data } = await res.json();
console.log(data.screenshot_url);
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.get(
    "https://api.prefetch.io/screenshot",
    params={"url": "https://stripe.com", "device": "pixel_7", "format": "webp", "block_ads": "true"},
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
)
print(r.json()["data"]["screenshot_url"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "url": "https://github.com",
    "screenshot_url": "https://assets.prefetch.io/screenshots/github-iphone15.jpg",
    "viewport": { "width": 393, "height": 659 },
    "format": "jpeg",
    "full_page": false,
    "captured_at": "2026-10-13T09:36:12.000Z",
    "device": "iphone_15",
    "device_scale_factor": 3,
    "dark_mode": true,
    "selector": null
  },
  "meta": {
    "requestId": "c1d2e3f4-5a6b-7c8d-9e0f-1a2b3c4d5e6f",
    "durationMs": 2450
  }
}
```

`viewport` is in CSS pixels. The image is `viewport × device_scale_factor` pixels, so an `iphone_15` capture is 1,179 pixels wide. `warnings` appears when something wasn't as you asked but the capture still happened, for example a `wait_for_selector` that never appeared.

## Devices

| `device` | Viewport | Density |
| - | - | - |
| `iphone_15` | 393 × 659 | 3× |
| `iphone_15_pro_max` | 430 × 739 | 3× |
| `iphone_se` | 320 × 568 | 2× |
| `pixel_7` | 412 × 839 | 2.625× |
| `galaxy_s8` | 360 × 740 | 3× |
| `ipad` | 810 × 1080 | 2× |
| `ipad_mini` | 768 × 1024 | 2× |
| `ipad_pro_11` | 834 × 1194 | 2× |
| `galaxy_tab_s4` | 712 × 1138 | 2.25× |
| `desktop_retina` | 1280 × 720 | 2× |

A device sets the viewport, so `width` and `height` are ignored when you pass one.

## Elements

`selector` captures the first element that matches a CSS selector, whole: `#pricing`, `header`, `.hero img`. Prefetch waits up to 10 seconds for it. If nothing matches, the request fails with `422` and `TARGET_ELEMENT_NOT_FOUND`, and isn't charged. An element can't be captured as a PDF.

`wait_for_selector` is different: it's best effort. The page is captured once the selector appears, or after 10 seconds, with a warning, if it never does.

## Formats

| Format | Best for | Notes |
| - | - | - |
| `jpeg` | General use, thumbnails | Smallest files, lossy. `quality` 1–100, default 85. |
| `png` | Logos, UI elements, exact pixels | Lossless, larger files. |
| `webp` | Web display | Best size for the quality. `quality` 1–100, default 85. |
| `pdf` | Documents, archiving | The whole page, printed with backgrounds. |

Images larger than 8 MB, such as a long page at a phone's pixel density, are scaled down until they fit.

## Limits

| Parameter | Default | Range |
| - | - | - |
| `width` | 1440 | 320–2560 |
| `height` | 900 | 240–5000 |
| `format` | `jpeg` | `jpeg`, `png`, `webp`, `pdf` |
| `full_page` | `false` | |
| `device` | none | See [Devices](#devices) |
| `dark_mode` | `false` | |
| `selector` | none | A CSS selector, up to 200 characters |
| `wait_for` | 0 | 0–30,000 ms |
| `wait_for_selector` | none | A CSS selector, up to 200 characters |
| `block_ads` | `false` | |
| `quality` | 85 | 1–100 |

## Credits

**1 credit** per capture, whatever the options. Failures are never charged.

## Next

> [card] [Batch screenshots](/jobs/batches)
>
> Capture up to 500 URLs in one job with `POST /batch/screenshot`.

> [card] [API reference](/api-reference/endpoint/screenshot)
>
> Every parameter, and a playground to try it.


# Search
Source: https://docs.prefetch.io/web-data/search

Search the web and get each result's title, URL and snippet, optionally with every result page scraped. 2 credits per 10 results.

`/search` runs a web search (Google results) and returns the results best first: each one's `url`, `title` and `description` (the snippet the search engine shows). Set `type=news` for recent articles with their publisher and date.

Ask for page content, and every result page is scraped in the same request, exactly as [`/scrape`](/web-data/scrape) would scrape it, and returned in `scrape` on its result. One call answers "find pages about X and give me their text".

Use `/search` to **find** pages. For a researched answer with sources, use [`/answers`](/web-data/answers). When you already know the page, use `/scrape`.

## Example requests

```bash Results only theme={"theme":"css-variables"}
curl "https://api.prefetch.io/search?query=open+source+CRM&limit=10" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash With page content theme={"theme":"css-variables"}
curl "https://api.prefetch.io/search?query=stripe+pricing&limit=5&formats=markdown" \
  -H "X-API-Key: $PREFETCH_API_KEY"
```

```bash POST, news from the past week theme={"theme":"css-variables"}
curl -X POST "https://api.prefetch.io/search" \
  -H "X-API-Key: $PREFETCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "series A funding developer tools",
    "type": "news",
    "time_range": "week",
    "limit": 5,
    "scrape_options": { "formats": ["summary"] }
  }'
```

```javascript Node.js theme={"theme":"css-variables"}
const res = await fetch("https://api.prefetch.io/search", {
  method: "POST",
  headers: { "X-API-Key": process.env.PREFETCH_API_KEY, "Content-Type": "application/json" },
  body: JSON.stringify({
    query: "headless CMS comparison",
    limit: 5,
    exclude_domains: ["pinterest.com"],
    scrape_options: { formats: ["markdown"], only_main_content: true },
  }),
});
const { data } = await res.json();
for (const r of data.results) {
  console.log(r.position, r.url, r.scrape?.markdown?.content.slice(0, 200) ?? r.scrape_error?.error);
}
```

```python Python theme={"theme":"css-variables"}
import os, requests

r = requests.post(
    "https://api.prefetch.io/search",
    headers={"X-API-Key": os.environ["PREFETCH_API_KEY"]},
    json={
        "query": "headless CMS comparison",
        "limit": 5,
        "scrape_options": {"formats": ["markdown"]},
    },
)
for result in r.json()["data"]["results"]:
    print(result["position"], result["url"])
```

## Example response

```json theme={"theme":"css-variables"}
{
  "success": true,
  "data": {
    "query": "stripe pricing",
    "type": "web",
    "results": [
      {
        "position": 1,
        "url": "https://stripe.com/pricing",
        "title": "Pricing & Fees | Stripe",
        "description": "Find Stripe fees and pricing information. Find information on pricing for payments, billing…",
        "date": null,
        "source": null,
        "image_url": null,
        "scrape": {
          "url": "https://stripe.com/pricing",
          "final_url": "https://stripe.com/pricing",
          "domain": "stripe.com",
          "status_code": 200,
          "metadata": { "title": "Pricing & Fees | Stripe", "language": "en", "content_type": "text/html" },
          "markdown": { "content": "# Pricing\n\nIntegrated per-transaction pricing…", "char_count": 18233, "word_count": 2611, "truncated": false, "main_content_only": true }
        }
      },
      {
        "position": 2,
        "url": "https://www.g2.com/products/stripe/pricing",
        "title": "Stripe Pricing 2026",
        "description": "Stripe pricing and plans…",
        "date": null,
        "source": null,
        "image_url": null,
        "scrape_error": {
          "error": "The target URL could not be accessed. The site may be blocking automated requests.",
          "error_code": "TARGET_BLOCKED"
        }
      }
    ],
    "count": 2,
    "scraped": 1,
    "warnings": ["1 result page(s) could not be scraped; see each result's scrape_error. They were not charged."]
  },
  "meta": { "requestId": "6f1d2c3b-4a5e-4f60-8b7a-9c0d1e2f3a4b", "durationMs": 8230 }
}
```

## Narrowing a search

| Parameter | Does |
| - | - |
| `type` | `web` (default) or `news`. News results carry `source` (the publisher), `date` and `image_url`. |
| `time_range` | `hour`, `day`, `week`, `month` or `year`. |
| `country`, `language` | Two-letter codes, such as `country=de&language=de`. |
| `location` | A city or region to search from, such as `Berlin, Germany`. |
| `include_domains` | Search only these domains (up to 10). |
| `exclude_domains` | Leave these out (up to 10). |

Search operators work in `query` the way they do on Google: `"exact phrase"`, `-word`, `filetype:pdf` and `site:example.com`.

Results on your account's blocklist are dropped, and the rest renumbered.

## Scraping the results

Ask for content with `formats` on `GET` (for example `formats=markdown,links`, plus `only_main_content` and `max_age`), or a `scrape_options` object on `POST` with any option [`/scrape`](/web-data/scrape) takes. Up to **10** results can be scraped in one request.

Result pages are fetched in parallel within one deadline: 45 seconds by default, and `timeout` can shorten it. A page that can't be fetched (blocked, too slow, not a page) gets a `scrape_error` with an [error code](/concepts/errors) instead of `scrape`, and isn't charged. The search itself still succeeds.

## Credits

| What | Credits |
| - | - |
| The search | **2 per 10 results** returned, rounded up, at least 2 |
| Each result page scraped | 1, or 4 with `summary`, `json` or `check_prompt_injection` |
| Result pages that couldn't be scraped | 0 |

A 10-result search costs 2 credits. With every page as markdown, it costs 12.

## Next

> [card] [Answers](/web-data/answers)
>
> A researched, sourced answer instead of a list of links.

> [card] [API reference](/api-reference/endpoint/search)
>
> Every parameter, and a playground to try it.