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

/agent/run/*

GET 

/agent/run/*

Poll an agent run: its status, the latest turn result and streamed step rationales, and the full turn transcript.

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]

Responses​

Schema
    idstringrequired

    Run ID.

    statusAgentRunStatusrequired

    Run status.

    Possible values: [capped, failed, needs_human, pending, running, stopped, succeeded, timed_out]

    humanRequest object

    Present while the run waits for a human, and with its outcome afterwards.

    reasonstringrequired

    Why the agent needs a human.

    Possible values: [login_wall, step_up_mfa]

    instructionsstring

    What the human should do.

    liveURLstring

    Live URL where the human completes the step.

    expiresAtstring

    ISO 8601 timestamp when the handoff expires.

    outcomestring

    How the handoff ended.

    Possible values: [closed, expired, resumed, stopped, userFailed]

    datarequired

    The latest turn's result, shaped by responseSchema when one was given.

    errorstringrequired

    The latest turn's error message, or null.

    stepsstring[]required

    Step rationales for the latest turn.

    actions object[]required

    Every tool call the latest turn made, appended as each finishes; seq gives call order.

  • Array [
  • seqnumberrequired

    1-based tool-call order within the turn, continuing across human handoffs.

    startedAtstringrequired

    ISO 8601 time the tool call started.

    durationMsnumberrequired

    Milliseconds until the result, or null when incomplete.

    toolstringrequired

    Tool the agent called.

    commands object[]required

    Browser commands in this call.

  • Array [
  • methodstringrequired

    Browser command name, or unknown when the agent sent one that does not exist.

    selectorstring

    Target selector with attribute values replaced by REDACTED; omitted when it cannot be shown safely.

    urlstring

    Navigation URL with credentials and query values redacted and fragment removed.

    textLengthnumber

    Length of typed text; the text itself is never returned.

  • ]
  • statusstringrequired

    Outcome.

    Possible values: [error, incomplete, ok]

    errorCodestring

    Bounded MCP error category, when available; never the error message.

  • ]
  • htmlstringrequired

    Requested page HTML, or null.

    markdownstringrequired

    Requested page Markdown, or null.

    linksstring[]required

    Requested links extracted from the page, or null.

    screenshotstringrequired

    Requested viewport PNG encoded as base64, or null.

    formatErrors object

    Present only for missing requested captures; maps format names to reason codes.

    htmlAgentFormatError

    Possible values: [blocked_saved_credentials, capture_failed, not_captured, session_unavailable, too_large]

    markdownAgentFormatError

    Possible values: [blocked_saved_credentials, capture_failed, not_captured, session_unavailable, too_large]

    linksAgentFormatError

    Possible values: [blocked_saved_credentials, capture_failed, not_captured, session_unavailable, too_large]

    screenshotAgentFormatError

    Possible values: [blocked_saved_credentials, capture_failed, not_captured, session_unavailable, too_large]

    replayErrorstring

    Present only when replay: true was requested and the run couldn't provision a recordable session.

    Constant value: session_unavailable
    replayIdstring

    Present when replay: true was requested and the recording was saved. Open it at /account/session-replay/player?id=<replayId>.

    turns object[]required

    The turn transcript.

  • Array [
  • turnIdstringrequired

    Turn ID.

    querystringrequired

    The task submitted for this turn.

    statusAgentRunStatusrequired

    Turn status.

    Possible values: [capped, failed, needs_human, pending, running, stopped, succeeded, timed_out]

    datarequired

    The turn's result, same shape as the top-level data.

    stepsstring[]required

    Step rationales for this turn.

    actions object[]required

    Every tool call this turn made, appended as each finishes; seq gives call order.

  • Array [
  • seqnumberrequired

    1-based tool-call order within the turn, continuing across human handoffs.

    startedAtstringrequired

    ISO 8601 time the tool call started.

    durationMsnumberrequired

    Milliseconds until the result, or null when incomplete.

    toolstringrequired

    Tool the agent called.

    commands object[]required

    Browser commands in this call.

  • Array [
  • methodstringrequired

    Browser command name, or unknown when the agent sent one that does not exist.

    selectorstring

    Target selector with attribute values replaced by REDACTED; omitted when it cannot be shown safely.

    urlstring

    Navigation URL with credentials and query values redacted and fragment removed.

    textLengthnumber

    Length of typed text; the text itself is never returned.

  • ]
  • statusstringrequired

    Outcome.

    Possible values: [error, incomplete, ok]

    errorCodestring

    Bounded MCP error category, when available; never the error message.

  • ]
  • unitsnumberrequired

    Units derived from the model tokens this turn consumed. Informational only: runs are billed for browser time.

    replayErrorstring

    Present only when replay: true was requested and the run couldn't provision a recordable session for this turn.

    Constant value: session_unavailable
    replayIdstring

    Present when replay: true was requested and the recording was saved. Open it at /account/session-replay/player?id=<replayId>.

  • ]
  • created_atstringrequired

    ISO 8601 timestamp when the run was created.

    completed_atstringrequired

    ISO 8601 timestamp when the run finished, or null while active.

    expires_atstringrequired

    ISO 8601 timestamp when the run's results expire, or null.

Was this page helpful?