SKskyvern-ai
agent

List runs

Changed on

List the organization's task and agent runs, newest first, filterable by status, run type, agent, a free-text search term, and failure category. Returns a paginated array of run summaries.

get/v1/runs

Request

  • Base URL
    https://api.skyvern.com
  • URL
    https://api.skyvern.com/v1/runs
  • Auth
    API key in header x-api-key

Query parameters

pageinteger
page_sizeinteger
statusRunStatus[] nullable
search_keystring nullable

Case-insensitive substring search (min 3 chars for trigram index) across the run's title, URL, run ID, agent (workflow) ID and inputs, plus a workflow run's webhook callback URL. 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. Browser profile and credential IDs apply to workflow runs; a browser session ID also matches a standalone task that used it.

Example:login_url
run_typeRunType[] nullable
workflow_permanent_idstring[] nullable

Filter to runs of these workflows (agents). Repeat the param to include multiple.

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.

failure_categorystring nullable

Exact-match filter on a workflow run's top classifier failure category (failure_category[0].category). Only failed, terminated, and timed_out runs are eligible; canceled runs are never returned by this filter. Applies to run_type=workflow_run only — combined with a task run_type it matches nothing.

Example:ANTI_BOT_DETECTION

Response

Successful Response

task_run_idstring required
run_idstring required
task_run_typestring required
statusstring required
titlestring nullable
started_atstring date-time nullable
finished_atstring date-time nullable
created_atstring date-time required
workflow_permanent_idstring nullable
workflow_deletedboolean
script_runboolean
trigger_type'manual' | 'mcp' | 'api' | 'scheduled' | 'webhook' | 'event' | 'job_recipe_extract' | 'job_recipe_apply' | 'seo_recipe_submit'

How a workflow run was initiated.

  • manual: User clicked "Run" in the UI
  • mcp: First-party MCP client or Skyvern CLI 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
  • seo_recipe_submit: Launched by an SEO recipe directory submission
created_bystring nullable

ID of the user who started the run

Changes

  • dc7de12b8e80Revision changes
    • warning

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

  • 539f04093540Revision changes
    • warning

      deleted the header request parameter x-api-key

    • info

      the endpoint scheme security ApiKeyAuth was added to the API