Skyvern: Get all runs by agent

Skyvern runs.getWorkflowRunsById: arguments, response, policy and SDK examples.

Operation skyvern.get_workflow_runs_by_id_v1_workflows_workflow_id_runs_get

Provider route: GET /v1/agents/{workflow_id}/runs. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/skyvern with npm, or alter-sdk-skyvern with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { SkyvernIntegration } from "@alter-ai/skyvern";

async function execute(input: Parameters<SkyvernIntegration["runs"]["getWorkflowRunsById"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new SkyvernIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.runs.getWorkflowRunsById(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_skyvern import SkyvernIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = SkyvernIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.runs.get_workflow_runs_by_id(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
`$`	object	Root	Additional keys: not allowed
`path`	object	Required within parent	Additional keys: not allowed
`path.workflow_id`	string	Required within parent
`query`	object	Optional	Additional keys: not allowed
`query.page`	integer	Optional	Page number for pagination. Default: 1 Minimum: 1
`query.page_size`	integer	Optional	Number of runs to return per page. Default: 10 Minimum: 1
`query.status`	JSON	Optional	Filter by one or more run statuses.
`query.status (anyOf 1)`	array	Alternative
`query.status (anyOf 1)[]`	string	Each item	One of: created, queued, running, failed, terminated, canceled, timed_out, completed, paused
`query.status (anyOf 2)`	null	Alternative
`query.search_key`	JSON	Optional	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.
`query.search_key (anyOf 1)`	string	Alternative	Maximum length: 500
`query.search_key (anyOf 2)`	null	Alternative
`query.error_code`	JSON	Optional	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.
`query.error_code (anyOf 1)`	string	Alternative	Maximum length: 500
`query.error_code (anyOf 2)`	null	Alternative
`query.created_at_start`	JSON	Optional	Only include runs created at or after this UTC timestamp (ISO 8601).
`query.created_at_start (anyOf 1)`	string	Alternative	Format: date-time
`query.created_at_start (anyOf 2)`	null	Alternative
`query.created_at_end`	JSON	Optional	Only include runs created strictly before this UTC timestamp (ISO 8601).
`query.created_at_end (anyOf 1)`	string	Alternative	Format: date-time
`query.created_at_end (anyOf 2)`	null	Alternative
`query.tags`	JSON	Optional	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.
`query.tags (anyOf 1)`	array	Alternative	Maximum items: 20
`query.tags (anyOf 1)[]`	string	Each item
`query.tags (anyOf 2)`	null	Alternative
`query.include_child_runs`	boolean	Optional	Include child workflow runs — runs started from inside another workflow run. Excluded by default so the history shows only top-level runs. Default: false

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
`$`	array	Root
`$[]`	Model	Each item	Expand Get all runs — response body — item

Referenced models: Get all runs — response body — item

Schemas

1 more schema is linked from the tables above, on the schema pages.

Get a session — response body — browser settings timezone id

Field	Type	Presence	Description and constraints
`$`	object	Root
`timezone_id`	JSON	Optional	IANA timezone the browser reports to pages, for example `America/New_York`. Applied when a browser is created and takes precedence over any timezone implied by the proxy location. Offsets such as `+03:00` are rejected. Omit or set to null to keep the default behavior.
`timezone_id (anyOf 1)`	string	Alternative
`timezone_id (anyOf 2)`	null	Alternative

Update an agent — response body — proxy location city, country, is ISP, subdivision

Field	Type	Presence	Description and constraints
`$`	object	Root	Granular proxy geo-targeting request with country, optional subdivision, and optional city.
`city`	JSON	Optional	City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
`city (anyOf 1)`	string	Alternative	Maximum length: 100
`city (anyOf 2)`	null	Alternative
`country`	string	Required within parent	ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE') Maximum length: 2 Minimum length: 2
`isISP`	boolean	Optional	Whether this geo target is marked as an ISP proxy location. Default: false
`subdivision`	JSON	Optional	ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
`subdivision (anyOf 1)`	string	Alternative	Maximum length: 10
`subdivision (anyOf 2)`	null	Alternative

Field	Type	Presence	Description and constraints
`$`	string	Root	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 Known values: override, picked, own_memory, credential, fresh, degraded_fresh

Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown

Field	Type	Presence	Description and constraints
`$`	object	Root
`actual_timezone_id`	JSON	Optional	The timezone the browser reported when measured, or null when it could not be measured.
`actual_timezone_id (anyOf 1)`	string	Alternative
`actual_timezone_id (anyOf 2)`	null	Alternative
`requested_timezone_id`	string	Required within parent	The timezone that was requested.
`source`	string	Required within parent	Where the requested setting came from. Known values: workflow_version, session_request, existing_session
`status`	string	Required within parent	`verified` when the browser reported the requested timezone or an IANA alias of it (Chromium reports `Asia/Calcutta` for `Asia/Kolkata`), `mismatch` when it reported another zone, `unapplied` when the browser already existed and was left unchanged, `unknown` when it could not be measured. Known values: verified, mismatch, unapplied, unknown
`warning`	JSON	Optional
`warning (anyOf 1)`	string	Alternative
`warning (anyOf 2)`	null	Alternative

Update an agent — response body — proxy location string

Field	Type	Presence	Description and constraints
`$`	string	Root	Known values: 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

Field	Type	Presence	Description and constraints
`$`	object	Root
`ai_fallback_triggered`	boolean	Optional	Default: false
`script_id`	JSON	Optional
`script_id (anyOf 1)`	string	Alternative
`script_id (anyOf 2)`	null	Alternative
`script_revision_id`	JSON	Optional
`script_revision_id (anyOf 1)`	string	Alternative
`script_revision_id (anyOf 2)`	null	Alternative

Field	Type	Presence	Description and constraints
`$`	object	Root
`attempt_number`	JSON	Required within parent
`attempt_number (anyOf 1)`	integer	Alternative	One-based number of this workflow run attempt
`attempt_number (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`decision_reason`	JSON	Optional	Reason recorded for the retry decision
`decision_reason (anyOf 1)`	string	Alternative
`decision_reason (anyOf 2)`	null	Alternative
`error_codes`	array	Optional	Error codes reported by this attempt
`error_codes[]`	string	Each item
`failure_reason`	JSON	Optional	Reason for failure, if the attempt failed
`failure_reason (anyOf 1)`	string	Alternative
`failure_reason (anyOf 2)`	null	Alternative
`finished_at`	JSON	Optional	Timestamp when this attempt finished
`finished_at (anyOf 1)`	string	Alternative	Format: date-time
`finished_at (anyOf 2)`	null	Alternative
`next_attempt_at`	JSON	Optional	Timestamp when the next attempt is scheduled
`next_attempt_at (anyOf 1)`	string	Alternative	Format: date-time
`next_attempt_at (anyOf 2)`	null	Alternative
`retry_decision`	JSON	Optional	Retry decision recorded for this attempt
`retry_decision (anyOf 1)`	string	Alternative
`retry_decision (anyOf 2)`	null	Alternative
`started_at`	JSON	Optional	Timestamp when this attempt started
`started_at (anyOf 1)`	string	Alternative	Format: date-time
`started_at (anyOf 2)`	null	Alternative
`status`	string	Required within parent	Status of this workflow run attempt Known values: created, queued, running, paused, timed_out, failed, terminated, completed, canceled
`webhook_sent_at`	JSON	Optional	Timestamp when the webhook for this attempt was sent
`webhook_sent_at (anyOf 1)`	string	Alternative	Format: date-time
`webhook_sent_at (anyOf 2)`	null	Alternative

List runs — response body — item trigger type How a workflow run was initiated

Field	Type	Presence	Description and constraints
`$`	string	Root	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 Known values: manual, mcp, api, scheduled, webhook, event, job_recipe_extract, job_recipe_apply, seo_recipe_submit

Policy, approvals and errors

SDK function policy ID: skyvern.get_workflow_runs_by_id_v1_workflows_workflow_id_runs_get. Catalog operation: get_workflow_runs_by_id_v1_workflows__workflow_id__runs_get. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source

Report an issue with this page