Skip to main content
POST
cURL
Always pass a tasks array, including for a single task. Each request creates one run, called a batch in response types. Authentication uses Authorization: Bearer $PREDEV_API_KEY or x-api-key.

Task controls

Every task needs a full HTTP(S) url and either a nonblank instruction or a non-empty output JSON Schema object. String-valued input is optional and does not replace instructions. Choose mode: "extract" for schema-oriented reads or mode: "agent" for goal-driven navigation; auto lets the service choose. maxSteps and maxDurationSeconds set per-task budgets. For compatibility with MCP, use 150 steps and 5600 seconds. REST also accepts the older maxIterations and timeoutMs names; those take precedence if both forms are sent. Do not send both forms in new code. Defaults vary with the task and execution path, so set an explicit budget when your workflow depends on one.
When output is omitted, schema inference may be attempted. Supply your own schema for a predictable contract; a successful task does not always have data.

Input validation

The service validates the entire batch before charging credits, creating a run, or queueing browser work. Malformed URLs, missing instructions without an output schema, and domains with no DNS address return an actionable error with a code, a zero-based taskIndex, and a field when applicable. DNS verification has a five-second request budget. Temporary DNS failures return 503 with URL_CHECK_UNAVAILABLE; retry the submission later. No tasks are started when verification fails. This check verifies the hostname, not page availability: authenticated pages and bot-protected sites remain eligible for browser execution. The dashboard applies the same task and URL format checks before enabling Run. CSV instructions are checked after row-variable interpolation. Output-schema-only extraction remains supported through the API and MCP.

Synchronous

With neither async nor stream enabled, the connection waits for a BatchResult. Use this for short tasks. The quickstart contains complete curl and SDK examples.

Async

With async: true, HTTP 200 returns an initial result such as:
Save id, then poll the run or attach an SSE stream. totalCreditsUsed: 0 on this initial response does not mean no credit floor was charged at submission.

Streaming

With stream: true, the response is text/event-stream. If both stream and async are true, streaming takes precedence; the server does not reject that combination. Send only your intended mode for clarity.
Lines beginning with : are keepalive comments. The task index is zero-based. Individual task done events inside task_event do not finish the batch; wait for the outer SSE done event and inspect all task statuses. A submission stream does not provide the initial snapshot event or reliably expose a run ID before completion. Use async submission followed by an existing-run stream when you need a saved ID for recovery. Disconnecting does not cancel the work.

Billing and limits

  • The default request ceiling is 1,000 tasks. Your account’s in-flight cap can be much smaller and counts every submitted task, including queued work.
  • concurrency defaults to 5 and is clamped to 1–20. It controls parallelism within the run; it does not let you exceed your account limit.
  • Submission checks the credit floor of 0.1 credits per task. Successful tasks settle at at least that floor, with usage increasing for more complex work. Failed tasks settle at zero and their prepaid floor is refunded.
  • Browser billing uses $0.10 per credit. Treat the returned creditsUsed and totalCreditsUsed as the recorded task charges, not a forecast or a reserved amount.
  • Free accounts have a limited browser trial budget in addition to the account credit balance. An exhausted trial returns SUBSCRIPTION_REQUIRED.
Use queue status to size batches and errors to handle QUEUE_FULL, RATE_LIMITED, and billing responses. Capacity snapshots are advisory; another submission can consume capacity before yours arrives.

Idempotency

Send an Idempotency-Key header, or idempotencyKey in the JSON body, to recover an existing run from the last 24 hours. The header takes precedence. Use a unique key per logical submission and keep the payload stable across retries. A matching existing run returns HTTP 200 as JSON, including when stream: true was requested. Check the response content type. The current SDK methods and MCP tool do not expose this option; use direct REST when needed. See retry semantics.

Response schemas

The generated schema below describes the run and task fields. Get run status explains pending entries, task outcomes, retry counts, and timelines. The completed count alone is not a reliable completion signal; use batch status.

Authorizations

Authorization
string
header
required

Use a pre.dev API key from https://pre.dev/projects/key.

Headers

Idempotency-Key
string

Optional user-scoped 24-hour retry lookup. Reuse only for the same logical submission; concurrent first requests can still duplicate work.

Body

application/json
tasks
object[]
required

One or more tasks. Default server limit is 1,000, configurable by deployment; BATCH_TOO_LARGE reports the active limit.

Minimum array length: 1

A full HTTP(S) URL and either nonblank instructions or a non-empty output schema are required. The entire batch is validated before billing or queueing.

concurrency
integer
default:5

Requested parallelism; defaults to 5 and is clamped to 1–20. Account and service capacity may reduce effective parallelism.

Required range: 1 <= x <= 20
async
boolean
default:false

Return the batch ID immediately, then poll or attach to its stream.

stream
boolean
default:false

Return SSE; takes precedence over async.

idempotencyKey
string

Optional retry lookup key. Idempotency-Key header takes precedence. User-scoped lookup lasts 24 hours; concurrent first requests are not atomically deduplicated.

Response

Batch result, asynchronous ID, or SSE stream. Inspect Content-Type before parsing. A done batch can contain failed tasks; inspect each task status.

id
string
required

24-character record ID.

Pattern: ^[a-fA-F0-9]{24}$
results
(object | null)[]
required

Ordered by task index. Slots can be null or partial until a result arrives.

status
enum<string>
required
Available options:
processing,
completed,
failed
name
string | null
taskNames
string[]
total
integer
completed
integer

Counts result slots, including pending/running placeholders or nulls. Do not use this as the completion signal.

totalCreditsUsed
number
createdAt
string<date-time>
completedAt
string<date-time> | null
liveEvents
object[][]

Per-task events when includeEvents=true and live events are available.

error
string | null