API Reference

Complete reference for the Scraper REST API. All endpoints require authentication via API key.

Authentication

Include your API key in the X-API-Key header with every request. Generate keys from the dashboard under Settings > API Keys.

Header

X-API-Key: scr_live_your_key_here

Base URL

https://scraper.bot/api

GET/flows

List all flows. Supports filtering by status and mode.

Query Parameters

Name	Type	Description
`status`	string	Filter by flow status: active, paused, draft, error
`mode`	string	Filter by flow mode: extract, interact, monitor

Response

JSON

{
  "data": [
    {
      "id": "flow-1",
      "name": "Product Price Monitor",
      "status": "active",
      "mode": "monitor",
      "url": "https://example-store.com/products",
      "successRate": 98.5,
      "totalRuns": 248,
      "createdAt": "2026-02-15T10:00:00Z"
    }
  ],
  "total": 6
}

Examples

curl

curl https://scraper.bot/api/flows?status=active \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/flows?status=active", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/flows

Create a new flow.

Request Body

JSON

{
  "name": "My New Flow",
  "description": "Scrape product listings",
  "url": "https://example.com/products",
  "mode": "extract",
  "steps": [
    { "type": "navigate", "label": "Go to page" },
    { "type": "extract", "label": "Extract data" }
  ],
  "outputSchema": { "title": "string", "price": "number" }
}

Response

JSON

{
  "data": {
    "id": "flow-1710000000000",
    "name": "My New Flow",
    "status": "draft",
    "createdAt": "2026-03-18T12:00:00Z"
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/flows \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"My New Flow","url":"https://example.com","mode":"extract"}'

JavaScript

const res = await fetch("/api/flows", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My New Flow",
    url: "https://example.com",
    mode: "extract",
  }),
});
const { data } = await res.json();

GET/flows/:id

Get a single flow by ID.

Response

JSON

{
  "data": {
    "id": "flow-1",
    "name": "Product Price Monitor",
    "description": "Track prices across e-commerce sites",
    "url": "https://example-store.com/products",
    "mode": "monitor",
    "status": "active",
    "steps": [...],
    "outputSchema": { "name": "string", "price": "number" },
    "successRate": 98.5,
    "totalRuns": 248
  }
}

Examples

curl

curl https://scraper.bot/api/flows/flow-1 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/flows/flow-1", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

PUT/flows/:id

Update an existing flow. Merge-patches the provided fields.

Request Body

JSON

{
  "name": "Updated Flow Name",
  "status": "active"
}

Response

JSON

{
  "data": {
    "id": "flow-1",
    "name": "Updated Flow Name",
    "status": "active",
    "updatedAt": "2026-03-18T12:00:00Z"
  }
}

Examples

curl

curl -X PUT https://scraper.bot/api/flows/flow-1 \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"Updated Flow Name","status":"active"}'

JavaScript

const res = await fetch("/api/flows/flow-1", {
  method: "PUT",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Updated Flow Name" }),
});

DELETE/flows/:id

Delete a flow by ID.

Response

JSON

{
  "message": "Flow flow-1 deleted successfully"
}

Examples

curl

curl -X DELETE https://scraper.bot/api/flows/flow-1 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

await fetch("/api/flows/flow-1", {
  method: "DELETE",
  headers: { "X-API-Key": "scr_live_your_key_here" },
});

GET/runs

List all runs. Supports filtering by flow ID and status.

Query Parameters

Name	Type	Description
`flowId`	string	Filter runs by flow ID
`status`	string	Filter by run status: queued, running, completed, failed, cancelled

Response

JSON

{
  "data": [
    {
      "id": "run-1",
      "flowId": "flow-1",
      "flowName": "Product Price Monitor",
      "status": "completed",
      "startedAt": "2026-03-18T12:00:00Z",
      "duration": 12400,
      "itemsExtracted": 147,
      "cost": 0.003
    }
  ],
  "total": 5
}

Examples

curl

curl https://scraper.bot/api/runs?flowId=flow-1&status=completed \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/runs?flowId=flow-1", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/runs

Trigger a new run for a flow. The run starts in queued status.

Request Body

JSON

{
  "flowId": "flow-1"
}

Response

JSON

{
  "data": {
    "id": "run-1710000000000",
    "flowId": "flow-1",
    "flowName": "Product Price Monitor",
    "status": "queued",
    "startedAt": "2026-03-18T12:00:00Z",
    "cost": 0
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/runs \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"flowId":"flow-1"}'

JavaScript

const res = await fetch("/api/runs", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ flowId: "flow-1" }),
});

GET/runs/:id

Get a single run by ID, including full logs.

Response

JSON

{
  "data": {
    "id": "run-1",
    "flowId": "flow-1",
    "status": "completed",
    "duration": 12400,
    "itemsExtracted": 147,
    "logs": [
      { "timestamp": "...", "level": "info", "message": "Run started" },
      { "timestamp": "...", "level": "info", "message": "Extracted 147 items" }
    ],
    "outputPreview": [...]
  }
}

Examples

curl

curl https://scraper.bot/api/runs/run-1 \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/runs/run-1", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();
console.log(data.logs);

POST/extract

One-shot extraction. Send a URL and optional instructions to get structured data back instantly without creating a flow.

Request Body

JSON

{
  "url": "https://example-store.com/products",
  "instructions": "Extract all product names and prices",
  "schema": {
    "name": "string",
    "price": "number"
  }
}

Response

JSON

{
  "data": {
    "url": "https://example-store.com/products",
    "extractedAt": "2026-03-18T12:00:00Z",
    "itemCount": 3,
    "items": [
      { "name": "Wireless Headphones Pro", "price": 79.99 },
      { "name": "USB-C Hub 7-in-1", "price": 34.99 },
      { "name": "Mechanical Keyboard", "price": 129.99 }
    ]
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/extract \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example-store.com/products","instructions":"Extract all product names and prices"}'

JavaScript

const res = await fetch("/api/extract", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    url: "https://example-store.com/products",
    instructions: "Extract all product names and prices",
    schema: { name: "string", price: "number" },
  }),
});
const { data } = await res.json();
console.log(data.items);

GET/keys

List all API keys. Keys are returned masked for security.

Response

JSON

{
  "data": [
    {
      "id": "key-1",
      "name": "Production API Key",
      "key": "scr_live_****xxxx",
      "createdAt": "2026-01-15T10:00:00Z",
      "scopes": ["flows:read", "flows:write", "runs:read", "runs:write"]
    }
  ],
  "total": 3
}

Examples

curl

curl https://scraper.bot/api/keys \
  -H "X-API-Key: scr_live_your_key_here"

JavaScript

const res = await fetch("/api/keys", {
  headers: { "X-API-Key": "scr_live_your_key_here" },
});
const { data } = await res.json();

POST/keys

Create a new API key. The full key is only returned once on creation.

Request Body

JSON

{
  "name": "My New Key",
  "scopes": ["flows:read", "runs:read", "runs:write"]
}

Response

JSON

{
  "data": {
    "id": "key-1710000000000",
    "name": "My New Key",
    "key": "scr_live_abc123def456...",
    "createdAt": "2026-03-18T12:00:00Z",
    "scopes": ["flows:read", "runs:read", "runs:write"]
  }
}

Examples

curl

curl -X POST https://scraper.bot/api/keys \
  -H "X-API-Key: scr_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"name":"My New Key","scopes":["flows:read","runs:read"]}'

JavaScript

const res = await fetch("/api/keys", {
  method: "POST",
  headers: {
    "X-API-Key": "scr_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    name: "My New Key",
    scopes: ["flows:read", "runs:read"],
  }),
});
const { data } = await res.json();
// Save data.key - it won't be shown again

Ready to integrate?

Create your first flow in minutes. No credit card required.

Get Your API Key