Skyvern: Retry a run

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

Operation skyvern.retry_workflow_run_v1_workflows_runs_workflow_run_id_retry_post

Provider route: POST /v1/agents/runs/{workflow_run_id}/retry. 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"]["retryWorkflowRun"]>[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.retryWorkflowRun(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.retry_workflow_run(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_run_id`	string	Required within parent	The id of the workflow run to retry.
`headers`	object	Optional	Additional keys: not allowed
`headers.x-max-steps-override`	JSON	Optional
`headers.x-max-steps-override (anyOf 1)`	integer	Alternative
`headers.x-max-steps-override (anyOf 2)`	null	Alternative
`headers.x-user-agent`	JSON	Optional
`headers.x-user-agent (anyOf 1)`	string	Alternative
`headers.x-user-agent (anyOf 2)`	null	Alternative

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
`$`	Model	Root	Expand Login Task — response body

Referenced models: Login Task — response body

Schemas

6 more schemas are linked from the tables above, on the schema pages.

Field	Type	Presence	Description and constraints
`$`	object	Root
`ai_fallback`	JSON	Optional	Whether to fallback to AI if code run fails.
`ai_fallback (anyOf 1)`	boolean	Alternative
`ai_fallback (anyOf 2)`	null	Alternative
`app_url`	JSON	Optional	URL to the application UI where the run can be viewed
`app_url (anyOf 1)`	string	Alternative
`app_url (anyOf 2)`	null	Alternative
`attempt`	JSON	Optional
`attempt (anyOf 1)`	integer	Alternative	One-based number of the current workflow run attempt Default: 1
`attempt (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`attempts`	array	Optional	Attempts recorded for this workflow run
`attempts[]`	Model	Each item	Expand Login Task — response body — attempts item
`browser_profile_id`	JSON	Optional	ID of the browser profile used for this run
`browser_profile_id (anyOf 1)`	string	Alternative
`browser_profile_id (anyOf 2)`	null	Alternative
`browser_seed_source`	JSON	Optional	Which layer of the seed-precedence chain seeded this run's browser (provenance).
`browser_seed_source (anyOf 1)`	Model	Alternative	Expand Login Task — response body — browser seed source string
`browser_seed_source (anyOf 2)`	null	Alternative
`browser_session_id`	JSON	Optional	ID of the Skyvern persistent browser session used for this run
`browser_session_id (anyOf 1)`	string	Alternative
`browser_session_id (anyOf 2)`	null	Alternative
`browser_settings_receipt`	JSON	Optional	The timezone the run's browser reported against the one its workflow version requested. Null when the version requests no browser settings or the browser has not been measured yet.
`browser_settings_receipt (anyOf 1)`	Model	Alternative	Expand Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown
`browser_settings_receipt (anyOf 2)`	null	Alternative
`created_at`	string	Required within parent	Timestamp when this run was created Format: date-time
`downloaded_files`	JSON	Optional	List of files downloaded during the run
`downloaded_files (anyOf 1)`	array	Alternative
`downloaded_files (anyOf 1)[]`	Model	Each item	Expand Get a session — response body — recordings array item
`downloaded_files (anyOf 2)`	null	Alternative
`errors`	JSON	Optional	The errors for the run
`errors (anyOf 1)`	array	Alternative
`errors (anyOf 1)[]`	object	Each item	Additional keys: allowed
`errors (anyOf 2)`	null	Alternative
`failure_reason`	JSON	Optional	Reason for failure if the run failed or terminated
`failure_reason (anyOf 1)`	string	Alternative
`failure_reason (anyOf 2)`	null	Alternative
`finished_at`	JSON	Optional	Timestamp when this run finished
`finished_at (anyOf 1)`	string	Alternative	Format: date-time
`finished_at (anyOf 2)`	null	Alternative
`max_screenshot_scrolls`	JSON	Optional	The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot
`max_screenshot_scrolls (anyOf 1)`	JSON	Alternative
`max_screenshot_scrolls (anyOf 1) (anyOf 1)`	integer	Alternative
`max_screenshot_scrolls (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`max_screenshot_scrolls (anyOf 2)`	null	Alternative
`modified_at`	string	Required within parent	Timestamp when this run was last modified Format: date-time
`next_attempt_at`	JSON	Optional	Timestamp when the next workflow run attempt is scheduled
`next_attempt_at (anyOf 1)`	string	Alternative	Format: date-time
`next_attempt_at (anyOf 2)`	null	Alternative
`output`	JSON	Optional	Output data from the run, if any. Format/schema depends on the data extracted by the run.
`output (anyOf 1)`	object	Alternative	Additional keys: allowed
`output (anyOf 2)`	array	Alternative
`output (anyOf 2)[]`	JSON	Each item
`output (anyOf 3)`	string	Alternative
`output (anyOf 4)`	null	Alternative
`queued_at`	JSON	Optional	Timestamp when this run was queued
`queued_at (anyOf 1)`	string	Alternative	Format: date-time
`queued_at (anyOf 2)`	null	Alternative
`recording_archived`	boolean	Optional	True when the recording exists but has been archived to cold storage and is not currently accessible. Default: false
`recording_url`	JSON	Optional	URL to the recording of the run
`recording_url (anyOf 1)`	string	Alternative
`recording_url (anyOf 2)`	null	Alternative
`retry_pending`	boolean	Optional	Whether another attempt is scheduled for this workflow run Default: false
`run_id`	string	Required within parent	Unique identifier for this run. Run ID starts with `tsk_` for task runs and `wr_` for workflow runs.
`run_request`	JSON	Optional	The original request parameters used to start this workflow run
`run_request (anyOf 1)`	Model	Alternative	Expand Login Task — response body — run request ai fallback, browser address, browser profile id, browser session id, browser type, cdp connect headers, extra http headers, file ids, max elapsed time minutes, max screenshot scrolls, parameters, proxy location, reuse browser session, run metadata, run with, start fresh browser, title, totp identifier, totp url, webhook url, workflow id
`run_request (anyOf 2)`	null	Alternative
`run_type`	string	Required within parent	Type of run - always workflow_run for workflow runs Must equal: workflow_run
`run_with`	string	Optional	Whether the workflow run was executed with agent or code Default: agent
`screenshot_urls`	JSON	Optional	List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.
`screenshot_urls (anyOf 1)`	array	Alternative
`screenshot_urls (anyOf 1)[]`	string	Each item
`screenshot_urls (anyOf 2)`	null	Alternative
`script_id`	JSON	Optional	ID of the cached script used for this workflow run, if any.
`script_id (anyOf 1)`	string	Alternative
`script_id (anyOf 2)`	null	Alternative
`script_run`	JSON	Optional	The script run result
`script_run (anyOf 1)`	Model	Alternative	Expand Login Task — response body — script run ai fallback triggered, script id, script revision id
`script_run (anyOf 2)`	null	Alternative
`started_at`	JSON	Optional	Timestamp when this run started execution
`started_at (anyOf 1)`	string	Alternative	Format: date-time
`started_at (anyOf 2)`	null	Alternative
`status`	string	Required within parent	Current status of the run Known values: created, queued, running, paused, timed_out, failed, terminated, completed, canceled
`step_count`	JSON	Optional	Total number of steps executed in this run
`step_count (anyOf 1)`	JSON	Alternative
`step_count (anyOf 1) (anyOf 1)`	integer	Alternative
`step_count (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`step_count (anyOf 2)`	null	Alternative

Referenced models: Login Task — response body — browser seed source string, Login Task — response body — browser_settings_receipt / source: workflow version, session request, existing session, status: verified, mismatch, unapplied, unknown, Get a session — response body — recordings array item, Login Task — response body — script run ai fallback triggered, script id, script revision id, Login Task — response body — attempts item, Login Task — response body — run request ai fallback, browser address, browser profile id, browser session id, browser type, cdp connect headers, extra http headers, file ids, max elapsed time minutes, max screenshot scrolls, parameters, proxy location, reuse browser session, run metadata, run with, start fresh browser, title, totp identifier, totp url, webhook url, workflow id

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

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

Policy, approvals and errors

SDK function policy ID: skyvern.retry_workflow_run_v1_workflows_runs_workflow_run_id_retry_post. Catalog operation: retry_workflow_run_v1_workflows_runs__workflow_run_id__retry_post. 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