API Reference

Quick Start

Get your API key from app.scrapx.io → Settings → API.

Authentication

Pass your API key in the x-api-key header. No Workspace ID needed.

curl -X POST https://api.scrapx.io/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "agentTask": { ... }
  }'

Rate Limiting

Requests are counted per workspace per calendar day (UTC). The limit is configured in your workspace settings (maxAPIRequest, default 1000).

When the limit is exceeded the API returns 429 Too Many Requests.

Mode 1 — Agentic

Send a plain-text prompt. The AI agent launches a real browser, renders JavaScript, and returns a screenshot, raw HTML, or a data extract. No URL field, no credentials — just describe what you need.

Request body

Example — extract product prices

curl -X POST https://api.scrapx.io/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "agentTask": {
      "goal": "Go to shop.example.com/products and extract all product names and prices"
    }
  }'

Example — screenshot a JS-rendered page

curl -X POST https://api.scrapx.io/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "agentTask": {
      "goal": "Go to dashboard.example.com, wait for the charts to load, and take a screenshot",
      "output": "screenshot"
    }
  }'

Mode 2 — Command

Define exact browser steps. No AI per-step cost. Perfect for stable, well-known page structures.

Step types

returnType options

json (default) — returns all extract results as an object · text / html / markdown — final page content · screenshot — last screenshot taken, returned as an S3 URL (30-day TTL)

Example — search and extract results

curl -X POST https://api.scrapx.io/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "commandTask": {
      "url": "https://example.com",
      "steps": [
        { "action": "type", "selector": "input[name=q]", "value": "scrapx" },
        { "action": "wait", "ms": 1500 },
        { "action": "extract", "selector": "h3.result-title", "multiple": true, "as": "titles" },
        { "action": "extract", "selector": ".price", "multiple": true, "as": "prices" },
        { "action": "screenshot", "as": "final" }
      ],
      "returnType": "json"
    }
  }'

Response Format

Agentic mode — AI extract (200)

{
  "requestId": "uuid",
  "output": {
    "status": "success",
    "steps": 4,
    "result": { "data": "Product A: $12.99, Product B: $8.49", "format": "ai_extract" },
    "usage": { "promptTokens": 4200, "completionTokens": 80, "totalTokens": 4280, "estimatedCostUsd": 0.0011 },
    "sessionUrl": "https://...s3.amazonaws.com/.../response.json",
    "videoUrl": "https://...s3.amazonaws.com/.../agent-session.webm"
  }
}

Agentic mode — screenshot (200)

{
  "requestId": "uuid",
  "output": {
    "status": "success",
    "steps": 2,
    "result": { "data": "https://...s3.amazonaws.com/.../screenshot.png", "format": "screenshot" },
    "usage": { "promptTokens": 3100, "completionTokens": 42, "totalTokens": 3142, "estimatedCostUsd": 0.0008 },
    "sessionUrl": "https://...s3.amazonaws.com/.../response.json",
    "videoUrl": "https://...s3.amazonaws.com/.../agent-session.webm"
  }
}

Command mode (200)

{
  "requestId": "uuid",
  "output": {
    "status": "success",
    "steps": 3,
    "extractions": {
      "titles": ["Product A", "Product B"],
      "prices": ["$12.99", "$8.49"],
      "final": "https://...s3.amazonaws.com/.../screenshot-0.png"
    },
    "returnType": "json",
    "sessionUrl": "https://...s3.amazonaws.com/.../response.json"
  }
}

Error

{ "error": "Invalid API key" }
{ "error": "Rate limit exceeded", "limit": 1000, "used": 1001, "reset": 1716681600 }
{ "error": "Missing agentTask or commandTask in request body" }

Response Headers

Error Codes

Usage Endpoint

Check today's usage without executing a task.

GET https://api.scrapx.io/usage
x-api-key: YOUR_API_KEY

// Response
{
  "limit": 1000,
  "used": 47,
  "remaining": 953,
  "reset": 1716681600
}