From URL to usable data, with one API.

Make your first request

A capture is asynchronous. Create the task, poll its status, then read the saved result.

Authentication

Send the API key as a Bearer token on every /v1 request. Never expose the key in frontend code or browser URLs.

Current public API

These endpoints are implemented today. Planned fields and endpoints are deliberately omitted so examples can be copied into production code.

Create a capture

POST /v1/captures returns a task ID immediately. Both auto and browser currently run through the managed browser pool.

Task lifecycle

Use the task resource as the source of truth. Poll every three seconds unless Retry-After asks you to wait longer.

Poll, then read the result

Stop polling on every terminal state. Read /result only after SUCCESS; otherwise it returns RESULT_UNAVAILABLE.

const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

let task;
do {
  const response = await fetch(
    "https://fetchbeam.com/v1/tasks/6d06c8e8-…",
    { headers: { Authorization: "Bearer fb_live_YOUR_API_KEY" } }
  );
  ({ task } = await response.json());

  if (["FAILED", "TIMEOUT", "CANCELED"].includes(task.status)) {
    throw new Error(task.error_message || "Capture " + task.status);
  }
  if (task.status !== "SUCCESS") await delay(3000);
} while (task.status !== "SUCCESS");

const result = await fetch(
  "https://fetchbeam.com/v1/tasks/" + task.id + "/result",
  { headers: { Authorization: "Bearer fb_live_YOUR_API_KEY" } }
).then((response) => response.json());

AI organization

AI organization currently runs from the signed-in dashboard after a successful capture. The goal field is saved with the task and guides analysis, but creating a public API task does not invoke the model by itself.

Batch capture

Create multiple durable captures together, track ordered items, retry failed items, and merge successful results into one download.

Create a batch

curl -X POST https://fetchbeam.com/v1/batches \
  -H "Authorization: Bearer fb_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: batch-products-001" \
  -d '{
    "name": "Supplier pages",
    "urls": [
      "https://example.com/products/1",
      "https://example.com/products/2"
    ],
    "outputs": ["html", "text", "extract"]
  }'

Credits & limits

A successful browser capture costs 2 Credits, or one capture from an active package. Successful AI extraction costs 2 Credits pay-as-you-go, or 2 / 1 / 0 Credits with an active Developer / Pro / Business package. Failed reservations are released.

Default and trial limits

Errors

Errors use a stable code and include X-Request-Id. Preserve that header when contacting support.

{
  "success": false,
  "code": "INVALID_REQUEST",
  "error": "A readable message"
}