New: Headless Forms, the backend for your contact forms. 🚀 Want to test it?

// api reference

Web Scraper API

One endpoint, two modes. Send a plain-English prompt to the AI agent or script exact browser steps — render JavaScript, handle logins, and return JSON, HTML or a screenshot.

Agentic mode Command mode Response format Error codes

Quick Start

Base URL

https://e.customjs.io/ai-scraper

Get your API key from app.customjs.space.

Authentication

Pass your API key in the x-api-key header.

curl -X POST https://e.customjs.io/ai-scraper \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input": { ... }
  }'

Rate Limiting

Every response includes your current usage in the rate-limit headers.

Response Header	Description
x-ratelimit-limit	Maximum requests allowed in the current window
x-ratelimit-used	Requests used in the current window
x-ratelimit-remaining	Requests remaining in the current window

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

Field	Type	Description
input.goal	string	Required. Plain-language task — include the URL in your prompt, e.g. "Go to shop.example.com and extract all product names and prices"
input.maxSteps	number	Max browser actions (default 10)
input.output	string	`ai_extract` \| `text` \| `html` \| `markdown` \| `screenshot`
input.url	string	Optional starting URL. Alternatively include the URL directly in `goal`
input.credentials	object	Key/value pairs for login fields, e.g. `{"username": "...", "password": "..."}`. The agent fills in matching fields automatically

Example — extract product prices

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

Example — screenshot a JS-rendered page

curl -X POST https://e.customjs.io/ai-scraper \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input": {
      "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

Action	Fields	Description
navigate	url	Go to URL
click	selector	Click element (CSS selector or visible text)
type	selector, value	Type text into input
wait	ms	Wait milliseconds
extract	selector, multiple?, attribute?, as?	Extract text or attribute from element(s). `as` sets the key in the result
screenshot	as?	Full-page screenshot — returns an S3 URL (30-day TTL)
scroll	direction?, amount?	Scroll up or down by px
evaluate	expression, as?	Run custom JS in page context

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://e.customjs.io/ai-scraper \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input": {
      "url": "https://example.com",
      "commands": [
        { "action": "type", "selector": "input[name=q]", "value": "customjs" },
        { "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)

{
  "status": "success",
  "steps": 4,
  "events": [
    { "step": 1, "type": "decision", "action": "navigate", "url": "https://shop.example.com/products" },
    { "step": 4, "type": "result" }
  ],
  "result": { "data": "Product A: $12.99, Product B: $8.49", "format": "ai_extract" },
  "usage": { "promptTokens": 4200, "completionTokens": 80, "totalTokens": 4280, "estimatedCostUsd": 0.0011 },
  "screenshots": [
    { "step": 1, "url": "https://...s3.amazonaws.com/.../step-001.png" },
    { "step": 2, "url": "https://...s3.amazonaws.com/.../step-002.png" }
  ],
  "sessionUrl": "https://...s3.amazonaws.com/.../response.json"
}

Agentic mode — screenshot (200)

{
  "status": "success",
  "steps": 2,
  "events": [
    { "step": 1, "type": "decision", "action": "navigate", "url": "https://dashboard.example.com" }
  ],
  "result": { "data": "https://...s3.amazonaws.com/.../screenshot.png", "format": "screenshot" },
  "usage": { "promptTokens": 3100, "completionTokens": 42, "totalTokens": 3142, "estimatedCostUsd": 0.0008 },
  "screenshots": [
    { "step": 1, "url": "https://...s3.amazonaws.com/.../step-001.png" }
  ],
  "sessionUrl": "https://...s3.amazonaws.com/.../response.json"
}

Command mode (200)

{
  "status": "success",
  "steps": 5,
  "extractions": {
    "titles": ["Product A", "Product B"],
    "prices": ["$12.99", "$8.49"],
    "final": "https://...s3.amazonaws.com/.../step-005.png"
  },
  "events": [
    { "step": 1, "type": "action", "action": "type", "selector": "input[name=q]", "success": true },
    { "step": 5, "type": "action", "action": "screenshot", "success": true }
  ],
  "returnType": "json",
  "screenshots": [
    { "step": 5, "url": "https://...s3.amazonaws.com/.../step-005.png" }
  ],
  "sessionUrl": "https://...s3.amazonaws.com/.../response.json"
}

Error

{ "error": { "message": "Api Key is invalid" } }
{ "message": "Too Many Requests" }

Response Headers

Header	Description
Content-Type	`application/json` on success
x-ratelimit-limit	Maximum requests allowed in the current window
x-ratelimit-used	Requests used in the current window
x-ratelimit-remaining	Requests remaining in the current window

Error Codes

Code	Meaning
400	Bad request — missing or invalid body
401	Unauthorized — missing or invalid API key
429	Rate limit exceeded — check the `x-ratelimit-remaining` header
500	Internal error — task execution failed

// try it first

Prefer to play before you code?

Open the interactive playground on the product page. Describe a goal in plain English, watch the agent navigate live, and copy the generated curl or SDK snippet straight into your stack.

Open the playground Get an API key

playground.curl

curl -X POST https://e.customjs.io/ai-scraper \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "input": {
      "goal": "Open apple.com/shop and get the
               cheapest MacBook Air as JSON."
    }
  }'

600 free requests / month · no credit card