Get all runs

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

[
  {
    "workflow_run_id": "<string>",
    "workflow_id": "<string>",
    "workflow_permanent_id": "<string>",
    "organization_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "browser_session_id": "<string>",
    "browser_profile_id": "<string>",
    "debug_session_id": "<string>",
    "extra_http_headers": {},
    "cdp_connect_headers": {},
    "webhook_callback_url": "<string>",
    "webhook_failure_reason": "<string>",
    "totp_verification_url": "<string>",
    "totp_identifier": "<string>",
    "failure_reason": "<string>",
    "failure_category": [
      {}
    ],
    "parent_workflow_run_id": "<string>",
    "workflow_title": "<string>",
    "max_screenshot_scrolls": 123,
    "max_elapsed_time_minutes": 123,
    "browser_address": "<string>",
    "run_with": "<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>",
    "ai_fallback": true,
    "code_gen": true,
    "workflow_schedule_id": "<string>",
    "ignore_inherited_workflow_system_prompt": false,
    "copilot_session_id": "<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"
  }
]

Agents

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…`)
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)

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

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

agents

runs

Get all runs

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

[
  {
    "workflow_run_id": "<string>",
    "workflow_id": "<string>",
    "workflow_permanent_id": "<string>",
    "organization_id": "<string>",
    "created_at": "2023-11-07T05:31:56Z",
    "modified_at": "2023-11-07T05:31:56Z",
    "browser_session_id": "<string>",
    "browser_profile_id": "<string>",
    "debug_session_id": "<string>",
    "extra_http_headers": {},
    "cdp_connect_headers": {},
    "webhook_callback_url": "<string>",
    "webhook_failure_reason": "<string>",
    "totp_verification_url": "<string>",
    "totp_identifier": "<string>",
    "failure_reason": "<string>",
    "failure_category": [
      {}
    ],
    "parent_workflow_run_id": "<string>",
    "workflow_title": "<string>",
    "max_screenshot_scrolls": 123,
    "max_elapsed_time_minutes": 123,
    "browser_address": "<string>",
    "run_with": "<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>",
    "ai_fallback": true,
    "code_gen": true,
    "workflow_schedule_id": "<string>",
    "ignore_inherited_workflow_system_prompt": false,
    "copilot_session_id": "<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, and extra HTTP headers. A run is returned if any of these fields match. Soft-deleted parameter definitions are excluded from key/description matching.

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

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

debug_session_id

string | null

extra_http_headers

Extra Http Headers · object

Show child attributes

cdp_connect_headers

Cdp Connect Headers · object

Show child attributes

proxy_location

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

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

script_run

ScriptRunResponse · object

Show child attributes

job_id

string | null

depends_on_workflow_run_id

string | null

sequential_key

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
api: Direct API call to the run endpoint
scheduled: Triggered by a cron schedule
webhook: Triggered by an external system via the webhook endpoint

Available options:

manual,

api,

scheduled,

webhook

workflow_schedule_id

string | null

ignore_inherited_workflow_system_prompt

boolean

default:false

copilot_session_id

string | null

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

Retry a run

Get all runs by agent

⌘I