Skyvern: Run a task

Skyvern tasks.runTask: arguments, response, policy and SDK examples.

Operation skyvern.run_task_v1_run_tasks_post

Provider route: POST /v1/run/tasks. 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["tasks"]["runTask"]>[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.tasks.runTask(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.tasks.run_task(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
`$`	object	Root	Additional keys: not allowed
`headers`	object	Optional	Additional keys: not allowed
`headers.x-user-agent`	JSON	Optional
`headers.x-user-agent (anyOf 1)`	string	Alternative
`headers.x-user-agent (anyOf 2)`	null	Alternative
`body`	Model	Required within parent	Expand Run a task — request body — body

Referenced models: Run a task — request body — body

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 Run a task — response body

Referenced models: Run a task — response body

Schemas

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

Run a task — response body

Field	Type	Presence	Description and constraints
`$`	object	Root
`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
`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_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
`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
`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
`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 task run
`run_request (anyOf 1)`	Model	Alternative	Expand Run a task — response body — run request browser address, browser profile id, browser session id, cdp connect headers, data extraction schema, engine, error code mapping, extra http headers, file ids, include action history in verification, max screenshot scrolls, max steps, model, prompt, proxy location, publish workflow, run with, start fresh browser, title, totp identifier, totp url, url, webhook url
`run_request (anyOf 2)`	null	Alternative
`run_type`	string	Required within parent	Types of a task run - task_v1, task_v2, openai_cua, anthropic_cua, ui_tars Known values: task_v1, task_v2, task_v3, openai_cua, anthropic_cua, ui_tars, yutori_navigator
`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_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: Get a session — response body — recordings array item, Login Task — response body — script run ai fallback triggered, script id, script revision id, Run a task — response body — run request browser address, browser profile id, browser session id, cdp connect headers, data extraction schema, engine, error code mapping, extra http headers, file ids, include action history in verification, max screenshot scrolls, max steps, model, prompt, proxy location, publish workflow, run with, start fresh browser, title, totp identifier, totp url, url, webhook url

Get a session — response body — recordings array item

Field	Type	Presence	Description and constraints
`$`	object	Root	Information about a downloaded file, including URL and checksum.
`artifact_id`	JSON	Optional	Artifact row id for refresh-on-read
`artifact_id (anyOf 1)`	string	Alternative
`artifact_id (anyOf 2)`	null	Alternative
`checksum`	JSON	Optional	SHA-256 checksum of the file
`checksum (anyOf 1)`	string	Alternative
`checksum (anyOf 2)`	null	Alternative
`file_size`	JSON	Optional	Size of the file in bytes
`file_size (anyOf 1)`	JSON	Alternative
`file_size (anyOf 1) (anyOf 1)`	integer	Alternative
`file_size (anyOf 1) (anyOf 2)`	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
`file_size (anyOf 2)`	null	Alternative
`filename`	JSON	Optional	Original filename
`filename (anyOf 1)`	string	Alternative
`filename (anyOf 2)`	null	Alternative
`modified_at`	JSON	Optional	Modified time of the file
`modified_at (anyOf 1)`	string	Alternative	Format: date-time
`modified_at (anyOf 2)`	null	Alternative
`url`	string	Required within parent	URL to access the file

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

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

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

Policy, approvals and errors

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