Sign in

v65

latestOpenAPI 3.1.0raw.githubusercontent.com2026-08-0386234904.1 KB
Runs

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 fieldDescription
workflow_run_idThe unique run identifier (e.g. wr_123…)
Parameter keyThe key of any workflow parameter definition associated with the run
Parameter descriptionThe description of any workflow parameter definition
Run parameter valueThe actual value supplied for any parameter when the run was created
extra_http_headersExtra 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/v1/agents/runs

Query parameters

pageinteger

Page number for pagination.

Page number for pagination.

page_sizeinteger

Number of runs to return per page.

Number of runs to return per page.

statusWorkflowRunStatus[] nullable

Filter by one or more run statuses.

Filter by one or more run statuses.

search_keystring nullable

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.

Example:login_url

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.

error_codestring nullable

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.

Example:INVALID_CREDENTIALS

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.

Headers

x-api-keystring nullable

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

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

Response

Successful Response

workflow_run_idstring required
workflow_idstring required
workflow_permanent_idstring required
organization_idstring required
browser_session_idstring nullable
browser_profile_idstring nullable
browser_seed_source'override' | 'picked' | 'own_memory' | 'credential' | 'fresh' | 'degraded_fresh'

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
browser_sink_profile_idstring nullable
start_fresh_browserboolean nullable
debug_session_idstring nullable
status'created' | 'queued' | 'running' | 'failed' | 'terminated' | 'canceled' | 'timed_out' | 'completed' | 'paused' required
extra_http_headersobject nullable
cdp_connect_headersobject nullable
webhook_callback_urlstring nullable
webhook_failure_reasonstring nullable
totp_verification_urlstring nullable
totp_identifierstring nullable
failure_reasonstring nullable
failure_categoryobject[] nullable
retried_from_workflow_run_idstring nullable
fallback_attemptinteger nullable
parent_workflow_run_idstring nullable
workflow_titlestring nullable
max_screenshot_scrollsinteger nullable
max_elapsed_time_minutesinteger nullable
browser_addressstring nullable
run_withstring nullable
job_idstring nullable
depends_on_workflow_run_idstring nullable
sequential_keystring nullable
sequential_credential_idstring nullable
ai_fallbackboolean nullable
code_genboolean nullable
trigger_type'manual' | 'mcp' | 'api' | 'scheduled' | 'webhook'

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
workflow_schedule_idstring nullable
ignore_inherited_workflow_system_promptboolean
copilot_session_idstring nullable
credits_usedinteger
cached_credits_usedinteger
queued_atstring date-time nullable
started_atstring date-time nullable
finished_atstring date-time nullable
created_atstring date-time required
modified_atstring date-time required

Example response

[
  {
    "proxy_location": {
      "country": "US",
      "subdivision": "CA",
      "city": "New York"
    }
  }
]