/agent/run
POST/agent/run
Start an asynchronous AI agent run: a managed agent drives a real browser against a natural-language task and returns a structured JSON result. Returns a run ID to poll via GET /agent/run/{id}.
Request
Query Parameters
Possible values: [datacenter, residential]
Possible values: [0, 1, false, true]
Possible values: [0, 1, false, true]
Body
- Schema
- Example (auto)
Natural-language task for the agent. Minimum 10 characters.
Per-turn timeout in ms, clamped to [10000, 900000] (15-min hard cap).
Pause for human login/MFA in the same session. Default: fail. Does not extend timeout.
Possible values: [fail, pause]
webhook object
Optional webhook for terminal states and human handoffs.
Possible values: [failed, needs_human, succeeded]
responseSchema object
Best-effort JSON schema for the agent's final answer.
Best-effort JSON schema for the agent's final answer.
Soft cap on browser tool calls. Default 60, hard cap 90.
Navigation allowlist.
First navigation target.
Route browsing through a residential or datacenter proxy. Best-effort like the other hints below: injected into the agent's prompt, not enforced.
Possible values: [datacenter, residential]
Two-letter country code for the proxy exit (e.g. US).
Ask the agent to use stealth / anti-bot-detection mode.
Ask the agent to solve CAPTCHAs it encounters.
Name of a saved authentication profile to reuse.
Record the run as a session replay, viewable in the account dashboard.
When saved, the result and completion webhook include its replayId.
If the run can't provision a recordable browser session (for example, at
your concurrent-browser limit), it completes unrecorded and the result and
webhook include replayError: "session_unavailable".
Page captures to return with the result, taken from the agent's current tab when the run ends. Omit for none.
Possible values: [html, links, markdown, screenshot]
{
"query": "string",
"timeout": 0,
"onHumanNeeded": "fail",
"webhook": {
"url": "string",
"events": [
"failed"
]
},
"responseSchema": {},
"maxSteps": 0,
"allowedDomains": [
"string"
],
"startUrl": "string",
"proxy": "datacenter",
"proxyCountry": "string",
"stealth": true,
"solveCaptchas": true,
"profile": "string",
"replay": true,
"formats": [
"html"
]
}
Responses
- 200
- 400
- 401
- 403
- 404
- 408
- 429
- 500
- 503
Schema
- Fields
- Example (auto)
{
"id": "string",
"status": "string"
}
The request contains errors or didn't properly encode content.
The request is missing, or contains bad, authorization credentials.
The request targets a destination that is not allowed.
Resource couldn't be found.
The request took has taken too long to process.
Too many requests are currently being processed.
An internal error occurred when handling the request.
Service is unavailable.