Get all runs

List workflow runs across all workflows for the current organization.

Results are paginated and can be filtered by status, search_key, and error_code. All filters are combined with AND logic — a run must match every supplied filter to be returned.

search_key

A case-insensitive substring search that matches against any of the following fields:

Searched field	Description
workflow_run_id	The unique run identifier (e.g. wr_123…)
workflow_permanent_id	The permanent ID of the workflow that ran (e.g. wpid_123…)
Workflow title	The title of the workflow that ran
Parameter key	The key of any workflow parameter definition associated with the run
Parameter description	The description of any workflow parameter definition
Run parameter value	The actual value supplied for any parameter when the run was created
extra_http_headers	Extra HTTP headers attached to the run (searched as raw JSON text)
webhook_callback_url	The webhook URL the run posts its result to

Soft-deleted parameter definitions are excluded from key/description matching. A run is returned if any of the fields above contain the search term.

A complete identifier also matches the run that used it, by exact equality:

Identifier	Description
browser_profile_id	The browser profile the run used (e.g. bp_123…)
browser_session_id	The browser session the run used (e.g. pbs_123…)
Credential id	A credential the run used (e.g. cred_123…)

A complete browser profile or browser session id is matched against those identifiers only, not the text fields above. A credential id matches a run when it is the run’s sequential credential, the credential the run selected from a pool or fell back to, or the credential bound by a credential parameter on the run’s workflow version when the run was created and the run recorded no selection for that parameter. Other pool and fallback members the run did not use do not match.

error_code

An exact-match filter against the error_code field inside each task’s errors JSON array. A run matches if any of its tasks contains an error object with a matching error_code value. Error codes are user-defined strings set during workflow execution (e.g. INVALID_CREDENTIALS, LOGIN_FAILED, CAPTCHA_DETECTED).

Combining filters

All query parameters use AND logic:

• ?status=failed — only failed runs
• ?status=failed&error_code=LOGIN_FAILED — failed runs and have a LOGIN_FAILED error
• ?status=failed&error_code=LOGIN_FAILED&search_key=prod_credential — all three conditions must match

GET /v1/agents/runs

Get all runs

cURL

curl --request GET \
  --url https://api.skyvern.com/v1/agents/runs

200

[
  {
    "workflow_run_id": "<string>",
    "workflow_id": "<string>",
    "workflow_permanent_id": "<string>",
    "organization_id": "<string>",
    "status": "created",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "browser_session_id": "<string>",
    "browser_profile_id": "<string>",
    "browser_seed_source": "override",
    "browser_sink_profile_id": "<string>",
    "start_fresh_browser": true,
    "reuse_browser_session": true,
    "debug_session_id": "<string>",
    "attempt": 1,
    "retry_pending": false,
    "next_attempt_at": "2023-11-07T05:31:56Z",
    "attempts": [
      {
        "attempt_number": 123,
        "status": "created",
        "failure_reason": "<string>",
        "error_codes": [
          "<string>"
        ],
        "started_at": "2023-11-07T05:31:56Z",
        "finished_at": "2023-11-07T05:31:56Z",
        "retry_decision": "<string>",
        "decision_reason": "<string>",
        "next_attempt_at": "2023-11-07T05:31:56Z",
        "webhook_sent_at": "2023-11-07T05:31:56Z"
      }
    ],
    "extra_http_headers": {},
    "cdp_connect_headers": {},
    "proxy_location": "RESIDENTIAL",
    "webhook_callback_url": "<string>",
    "webhook_failure_reason": "<string>",
    "totp_verification_url": "<string>",
    "totp_identifier": "<string>",
    "failure_reason": "<string>",
    "failure_category": [
      {}
    ],
    "retried_from_workflow_run_id": "<string>",
    "fallback_attempt": 123,
    "parent_workflow_run_id": "<string>",
    "workflow_title": "<string>",
    "max_screenshot_scrolls": 123,
    "max_elapsed_time_minutes": 123,
    "browser_address": "<string>",
    "run_with": "<string>",
    "browser_type": "<string>",
    "browser_settings": {
      "timezone_id": "America/New_York"
    },
    "browser_settings_receipt": {
      "requested_timezone_id": "<string>",
      "source": "workflow_version",
      "status": "verified",
      "actual_timezone_id": "<string>",
      "warning": "<string>"
    },
    "script_run": {
      "ai_fallback_triggered": false,
      "script_id": "<string>",
      "script_revision_id": "<string>"
    },
    "job_id": "<string>",
    "depends_on_workflow_run_id": "<string>",
    "sequential_key": "<string>",
    "sequential_credential_id": "<string>",
    "ai_fallback": true,
    "code_gen": true,
    "trigger_type": "manual",
    "workflow_schedule_id": "<string>",
    "ignore_inherited_workflow_system_prompt": false,
    "copilot_session_id": "<string>",
    "created_by": "<string>",
    "credits_used": 0,
    "cached_credits_used": 0,
    "queued_at": "2023-11-07T05:31:56Z",
    "started_at": "2023-11-07T05:31:56Z",
    "finished_at": "2023-11-07T05:31:56Z"
  }
]

Headers

x-api-key · string | null

Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.

Query Parameters

page · integer · default: 1

Page number for pagination.

Required range: x >= 1

page_size · integer · default: 10

Number of runs to return per page.

Required range: x >= 1

status · enum<string>[] | null

Filter by one or more run statuses.

Available options: created, queued, running, failed, terminated, canceled, timed_out, completed, paused

search_key · string | null

Case-insensitive substring search across: workflow run ID, parameter key, parameter description, run parameter value, extra HTTP headers and webhook callback URL. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching. A complete browser profile ID, browser session ID or credential ID matches the run that used it exactly (no substring match). A complete browser profile or browser session ID is matched against those identifiers only, not the text fields. A credential ID matches when it is the run's sequential credential, the credential the run selected from a pool or fell back to, or the credential bound by a credential parameter on the run's workflow version when the run was created and the run recorded no selection for it. The workflow title and workflow permanent ID are matched as well.

Maximum string length: 500

Example:

"login_url"

error_code · string | null

Exact-match filter on the error_code field inside each task's errors JSON array. A run matches if any of its tasks contains an error with a matching error_code. Error codes are user-defined strings set during workflow execution.

Maximum string length: 500

Example:

"INVALID_CREDENTIALS"

Response

200

application/json

Successful Response

workflow_run_id · string · required

workflow_id · string · required

workflow_permanent_id · string · required

organization_id · string · required

status · enum<string> · required

Available options: created, queued, running, failed, terminated, canceled, timed_out, completed, paused

created_at · string<date-time> · required

modified_at · string<date-time> · required

browser_session_id · string | null

browser_profile_id · string | null

browser_seed_source · enum<string> | null

Which layer of the seed-precedence chain seeded a run's browser (provenance).

Resolved once at run setup, before any browser creation, for all run types (C-semantics).

• override: explicit request browser_profile_id (one-run-only pick via API)
• picked: the workflow's explicit profile pick (workflows.browser_profile_id) — "always start here"
• own_memory: the workflow's own auto-profile (no pick + persist_browser_session)
• credential: the run's selected credential's profile (rotation-aware; also the empty-own boot)
• fresh: no seed profile
• degraded_fresh: a resolved profile failed to load; ran fresh

Available options: override, picked, own_memory, credential, fresh, degraded_fresh

browser_sink_profile_id · string | null

start_fresh_browser · boolean | null

reuse_browser_session · boolean | null

debug_session_id · string | null

attempt · integer · default: 1

One-based number of the current workflow run attempt

retry_pending · boolean · default: false

Whether another attempt is scheduled for this workflow run

next_attempt_at · string<date-time> | null

Timestamp when the next workflow run attempt is scheduled

attempts · WorkflowRunAttempt · object[]

Attempts recorded for this workflow run

Show child attributes

extra_http_headers · Extra Http Headers · object | null

Show child attributes

cdp_connect_headers · Cdp Connect Headers · object | null

Show child attributes

proxy_location · enum<string> GeoTarget · object Proxy Location · object

Available options: RESIDENTIAL, US-CA, US-NY, US-TX, US-FL, US-WA, RESIDENTIAL_ES, RESIDENTIAL_IE, RESIDENTIAL_GB, RESIDENTIAL_IN, RESIDENTIAL_JP, RESIDENTIAL_FR, RESIDENTIAL_DE, RESIDENTIAL_NZ, RESIDENTIAL_ZA, RESIDENTIAL_AR, RESIDENTIAL_AU, RESIDENTIAL_BR, RESIDENTIAL_TR, RESIDENTIAL_CA, RESIDENTIAL_MX, RESIDENTIAL_IT, RESIDENTIAL_NL, RESIDENTIAL_PH, RESIDENTIAL_KR, RESIDENTIAL_SA, RESIDENTIAL_ISP, NONE

webhook_callback_url · string | null

webhook_failure_reason · string | null

totp_verification_url · string | null

totp_identifier · string | null

failure_reason · string | null

failure_category · Failure Category · object[] | null

retried_from_workflow_run_id · string | null

fallback_attempt · integer | null

parent_workflow_run_id · string | null

workflow_title · string | null

max_screenshot_scrolls · integer | null

max_elapsed_time_minutes · integer | null

browser_address · string | null

run_with · string | null

browser_type · string | null

browser_settings · BrowserSettings · object | null

Browser settings copied from the workflow version when the run was created

Show child attributes

browser_settings_receipt · BrowserSettingsReceipt · object | null

Show child attributes

script_run · ScriptRunResponse · object | null

Show child attributes

job_id · string | null

depends_on_workflow_run_id · string | null

sequential_key · string | null

sequential_credential_id · string | null

ai_fallback · boolean | null

code_gen · boolean | null

trigger_type · enum<string> | null

How a workflow run was initiated.

• manual: User clicked "Run" in the UI
• mcp: First-party MCP client request
• api: Direct API call to the run endpoint
• scheduled: Triggered by a cron schedule
• webhook: Triggered by an external system via the webhook endpoint
• job_recipe_extract: Launched by a job recipe extract request
• job_recipe_apply: Launched by a job recipe apply request

Available options: manual, mcp, api, scheduled, webhook, job_recipe_extract, job_recipe_apply

workflow_schedule_id · string | null

ignore_inherited_workflow_system_prompt · boolean · default: false

copilot_session_id · string | null

created_by · string | null

ID of the user who started the run

credits_used · integer · default: 0

cached_credits_used · integer · default: 0

queued_at · string<date-time> | null

started_at · string<date-time> | null

finished_at · string<date-time> | null