For AI agents: a documentation index is available at /llms.txt
Skip to main content

/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

    token string
    allowedDomains string[]
    credentials object
    externalProxyServer string
    integrationId string
    proxy ProxyType

    Possible values: [datacenter, residential]

    proxyCity string
    proxyCountry string
    proxyLocaleMatch string

    Possible values: [0, 1, false, true]

    proxyPreset string
    proxyState string
    proxySticky string

    Possible values: [0, 1, false, true]

Body

    querystringrequired

    Natural-language task for the agent. Minimum 10 characters.

    timeoutnumber

    Per-turn timeout in ms, clamped to [10000, 900000] (15-min hard cap).

    onHumanNeededstring

    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.

    urlstringrequired
    eventsstring[]

    Possible values: [failed, needs_human, succeeded]

    responseSchema object

    Best-effort JSON schema for the agent's final answer.

    object
    property name*any

    Best-effort JSON schema for the agent's final answer.

    maxStepsnumber

    Soft cap on browser tool calls. Default 60, hard cap 90.

    allowedDomainsstring[]

    Navigation allowlist.

    startUrlstring

    First navigation target.

    proxystring

    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]

    proxyCountrystring

    Two-letter country code for the proxy exit (e.g. US).

    stealthboolean

    Ask the agent to use stealth / anti-bot-detection mode.

    solveCaptchasboolean

    Ask the agent to solve CAPTCHAs it encounters.

    profilestring

    Name of a saved authentication profile to reuse.

    replayboolean

    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".

    formatsstring[]

    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]

Responses​

Schema
    idstringrequired
    statusstringrequired
Was this page helpful?