SKskyvern-ai
Runs

Get all runs by agent

Changed on

List runs for a specific workflow.

Supports filtering by status, search_key, and error_code. All filters are combined with AND logic.

search_key

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 workflow run ID matches that run. A complete task ID matches the workflow run the task ran in, when this list includes that run, or the standalone task itself where standalone tasks are listed. A complete browser profile, browser session, workflow run or task 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.

error_code

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.

include_child_runs

Child runs — runs this workflow started from inside another workflow run — are excluded by default, so the history shows only top-level runs. Pass include_child_runs=true to list them as well; every run carries a parent_workflow_run_id that is null for top-level runs.

get/v1/agents/{workflow_id}/runs

Request

  • Base URL
    https://api.skyvern.com
  • URL
    https://api.skyvern.com/v1/agents/{workflow_id}/runs
  • Auth
    none declared

Path parameters

workflow_idstring required

Query parameters

pageinteger

Page number for pagination.

page_sizeinteger

Number of runs to return per page.

statusWorkflowRunStatus[] nullable

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, 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 workflow run ID matches that run. A complete task ID matches the workflow run the task ran in, when this list includes that run, or the standalone task itself where standalone tasks are listed. A complete browser profile, browser session, workflow run or task 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.

Example:login_url
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
created_at_startstring date-time nullable

Only include runs created at or after this UTC timestamp (ISO 8601).

created_at_endstring date-time nullable

Only include runs created strictly before this UTC timestamp (ISO 8601).

tagsstring[] nullable

Filter by run tags. Each term is a label (production), a group (env:*), or a group:label (env:prod). Repeat the param or comma-separate (?tags=env:prod,env:staging). AND across distinct terms, OR within a group's labels (?tags=customer:acme,env:prod,env:staging -> customer=acme AND env in (prod, staging)). A label term matches the value across any/no group. Matches current tag values only.

include_child_runsboolean

Include child workflow runs — runs started from inside another workflow run. Excluded by default so the history shows only top-level runs.

Headers

x-api-keystring nullable

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
reuse_browser_sessionboolean nullable
debug_session_idstring nullable
status'created' | 'queued' | 'running' | 'failed' | 'terminated' | 'canceled' | 'timed_out' | 'completed' | 'paused' required
attemptinteger

One-based number of the current workflow run attempt

retry_pendingboolean

Whether another attempt is scheduled for this workflow run

next_attempt_atstring date-time nullable

Timestamp when the next workflow run attempt is scheduled

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
browser_typestring 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' | 'event' | 'job_recipe_extract' | 'job_recipe_apply'

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
  • event: Triggered by an external event source
  • job_recipe_extract: Launched by a job recipe extract request
  • job_recipe_apply: Launched by a job recipe apply request
workflow_schedule_idstring nullable
ignore_inherited_workflow_system_promptboolean
copilot_session_idstring nullable
created_bystring nullable

ID of the user who started the run

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"
    },
    "browser_settings": {
      "timezone_id": "America/New_York"
    }
  }
]

Changes

  • 0301d8690357Revision changes
    • warning

      added the new event enum value to the // response property for the response status

  • 04df18172f4dRevision changes
    • warning

      added the new job_recipe_apply enum value to the // response property for the response status

    • warning

      added the new job_recipe_extract enum value to the // response property for the response status

    • info

      added the new optional query request parameter include_child_runs

    • info

      added the new optional query request parameter tags

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property /// to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status