> ## Documentation Index
> Fetch the complete documentation index at: https://skyvern.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Run an agent

> Run an agent



## OpenAPI

````yaml /api-reference/openapi.json post /v1/run/agents
openapi: 3.1.0
info:
  title: Skyvern API
  description: API for Skyvern
  version: 1.0.0
servers:
  - url: https://api.skyvern.com
    x-fern-server-name: Cloud
security: []
paths:
  /v1/run/agents:
    post:
      tags:
        - Runs
      summary: Run an agent
      description: Run an agent
      operationId: run_workflow_v1_run_agents_post
      parameters:
        - name: template
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Template
        - name: x-max-steps-override
          in: header
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            title: X-Max-Steps-Override
        - name: x-user-agent
          in: header
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: X-User-Agent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WorkflowRunRequest-Input'
      responses:
        '200':
          description: Successfully ran agent
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WorkflowRunResponse'
        '400':
          description: Invalid agent run request
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
        '503':
          description: >-
            The server is busy dispatching other runs. No run was created; retry
            after Retry-After seconds.
          headers:
            Retry-After:
              description: Seconds to wait before retrying
              schema:
                type: integer
      security:
        - ApiKeyAuth: []
components:
  schemas:
    WorkflowRunRequest-Input:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: >-
            ID of the agent to run. Starts with `wpid_`. `workflow_id` is
            accepted as an alias.
          examples:
            - wpid_123
        parameters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameters
          description: Parameters to pass to the workflow
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: The title for this workflow run
        proxy_location:
          anyOf:
            - $ref: '#/components/schemas/ProxyLocation'
            - $ref: '#/components/schemas/GeoTarget'
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Proxy Location
          description: >-

            Geographic Proxy location to route the browser traffic through. This
            is only available in Skyvern Cloud.


            Available geotargeting options:

            - RESIDENTIAL: the default value. Skyvern Cloud uses a random US
            residential proxy.

            - RESIDENTIAL_ES: Spain

            - RESIDENTIAL_IE: Ireland

            - RESIDENTIAL_GB: United Kingdom

            - RESIDENTIAL_IN: India

            - RESIDENTIAL_JP: Japan

            - RESIDENTIAL_FR: France

            - RESIDENTIAL_DE: Germany

            - RESIDENTIAL_NZ: New Zealand

            - RESIDENTIAL_PH: Philippines

            - RESIDENTIAL_KR: South Korea

            - RESIDENTIAL_SA: Saudi Arabia

            - RESIDENTIAL_ZA: South Africa

            - RESIDENTIAL_AR: Argentina

            - RESIDENTIAL_AU: Australia

            - RESIDENTIAL_BR: Brazil

            - RESIDENTIAL_TR: Turkey

            - RESIDENTIAL_CA: Canada

            - RESIDENTIAL_MX: Mexico

            - RESIDENTIAL_IT: Italy

            - RESIDENTIAL_NL: Netherlands

            - RESIDENTIAL_ISP: ISP proxy

            - US-CA: California (deprecated, routes through RESIDENTIAL_ISP)

            - US-NY: New York (deprecated, routes through RESIDENTIAL_ISP)

            - US-TX: Texas (deprecated, routes through RESIDENTIAL_ISP)

            - US-FL: Florida (deprecated, routes through RESIDENTIAL_ISP)

            - US-WA: Washington (deprecated, routes through RESIDENTIAL_ISP)

            - NONE: No proxy


            For self-hosted deployments, you can pass a custom proxy URL as a
            dict: {"url": "http://user:password@proxy.example.com:8080"}. This
            routes the browser through your own proxy server and takes
            precedence over any globally configured proxy pool.
             Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}
          default: RESIDENTIAL
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: >-
            URL to send workflow status updates to after a run is finished.
            Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for
            webhook questions.
        totp_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Totp Url
          description: >

            URL that serves TOTP/2FA/MFA codes for Skyvern to use during the
            workflow run. Refer to
            https://www.skyvern.com/docs/credentials#let-skyvern-fetch-codes-from-your-endpoint
            for more details.
          examples:
            - https://my-totp-service.com/totp
        totp_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Totp Identifier
          description: >

            Identifier for the TOTP/2FA/MFA code when the code is pushed to
            Skyvern. Refer to
            https://www.skyvern.com/docs/credentials#push-a-code for more
            details.
          examples:
            - john.doe@example.com
            - '4155555555'
            - user_123
        browser_session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Session Id
          description: >-
            ID of a Skyvern browser session to reuse, having it continue from
            the current screen state
        reuse_browser_session:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Reuse Browser Session
          description: >-
            Override whether this run reuses the workflow's managed browser
            session. Null inherits the workflow setting. Without login
            credentials, a browser profile key, or a sequential key, reuse is
            workflow-scoped: every run shares one browser and its signed-in
            state, so treat the workflow as single-account.
        browser_profile_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Profile Id
          description: ID of a browser profile to reuse for this workflow run
        start_fresh_browser:
          type: boolean
          title: Start Fresh Browser
          description: >-
            When true, start this run from a fresh, empty browser and ignore any
            saved browser memory — no memory is read or written. A verified
            sign-in during the run still updates the credential's saved login.
          default: false
        max_screenshot_scrolls:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Screenshot Scrolls
          description: >-
            The maximum number of scrolls for the post action screenshot. When
            it's None or 0, it takes the current viewpoint screenshot.
        max_elapsed_time_minutes:
          anyOf:
            - type: integer
              maximum: 480
              minimum: 1
            - type: 'null'
          title: Max Elapsed Time Minutes
          description: >-
            Timeout this workflow run after the configured elapsed runtime in
            minutes. When omitted, the platform default is 240 minutes. The
            maximum configurable value is 480 minutes.
        extra_http_headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Extra Http Headers
          description: The extra HTTP headers for the requests in browser.
        cdp_connect_headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Cdp Connect Headers
          description: >-
            HTTP headers attached ONLY to the CDP WebSocket handshake when
            connecting to a remote browser via browser_address. Use this for
            browser-provider auth (e.g., x-api-key for Skyvern Cloud,
            Browserless, or similar). These headers are NEVER forwarded to
            target websites.
        browser_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Address
          description: The CDP address for the workflow run.
          examples:
            - http://127.0.0.1:9222
            - ws://127.0.0.1:9222/devtools/browser/1234567890
        ai_fallback:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Ai Fallback
          description: Whether to fallback to AI if the workflow run fails.
        run_with:
          anyOf:
            - type: string
            - type: 'null'
          title: Run With
          description: >-
            Whether to run the workflow with agent or code. Null inherits from
            the workflow setting.
          examples:
            - agent
            - code
        browser_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Type
          description: >-
            Browser engine for this run, one of the supported browser types
            (e.g. msedge, chrome, stealth-chromium). Overrides the
            workflow-level setting. Null inherits from the workflow.
          examples:
            - chrome
        run_metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Run Metadata
          description: >-
            String key/value metadata to attach to this workflow run for
            analytics tag filtering.
        file_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 50
            - type: 'null'
          title: File Ids
          description: >

            Ids of files uploaded through `POST /v1/upload_file` to attach to
            this run. Skyvern deletes an attached file as soon as the run
            finishes, so there is nothing to clean up afterwards. Reference an
            attached file by its id anywhere a file URL is accepted (for example
            in `parameters` or in the prompt) and no presigned URL is ever
            created for it. A file can be attached to one run at a time, and
            must not already be deleted.
          examples:
            - - file_123456789
      type: object
      required:
        - agent_id
      title: WorkflowRunRequest
    WorkflowRunResponse:
      properties:
        run_id:
          type: string
          title: Run Id
          description: >-
            Unique identifier for this run. Run ID starts with `tsk_` for task
            runs and `wr_` for workflow runs.
          examples:
            - tsk_123
            - tsk_v2_123
            - wr_123
        status:
          $ref: '#/components/schemas/RunStatus'
          description: Current status of the run
          examples:
            - created
            - queued
            - running
            - paused
            - timed_out
            - failed
            - terminated
            - completed
            - canceled
        output:
          anyOf:
            - additionalProperties: true
              type: object
            - items: {}
              type: array
            - type: string
            - type: 'null'
          title: Output
          description: >-
            Output data from the run, if any. Format/schema depends on the data
            extracted by the run.
        downloaded_files:
          anyOf:
            - items:
                $ref: '#/components/schemas/FileInfo'
              type: array
            - type: 'null'
          title: Downloaded Files
          description: List of files downloaded during the run
        recording_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Recording Url
          description: URL to the recording of the run
        recording_archived:
          type: boolean
          title: Recording Archived
          description: >-
            True when the recording exists but has been archived to cold storage
            and is not currently accessible.
          default: false
        screenshot_urls:
          anyOf:
            - items:
                type: string
              type: array
            - type: 'null'
          title: Screenshot Urls
          description: >-
            List of last n screenshot URLs in reverse chronological order - the
            first one the list is the latest screenshot.
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Reason
          description: Reason for failure if the run failed or terminated
        created_at:
          type: string
          format: date-time
          title: Created At
          description: Timestamp when this run was created
          examples:
            - '2025-01-01T00:00:00Z'
        modified_at:
          type: string
          format: date-time
          title: Modified At
          description: Timestamp when this run was last modified
          examples:
            - '2025-01-01T00:05:00Z'
        queued_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Queued At
          description: Timestamp when this run was queued
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
          description: Timestamp when this run started execution
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
          description: Timestamp when this run finished
        app_url:
          anyOf:
            - type: string
            - type: 'null'
          title: App Url
          description: URL to the application UI where the run can be viewed
          examples:
            - https://app.skyvern.com/tasks/tsk_123
            - https://app.skyvern.com/workflows/wpid_123/wr_123
        browser_session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Session Id
          description: ID of the Skyvern persistent browser session used for this run
          examples:
            - pbs_123
        browser_profile_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Profile Id
          description: ID of the browser profile used for this run
          examples:
            - bp_123
        max_screenshot_scrolls:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Screenshot Scrolls
          description: >-
            The maximum number of scrolls for the post action screenshot. When
            it's None or 0, it takes the current viewpoint screenshot
        script_run:
          anyOf:
            - $ref: '#/components/schemas/ScriptRunResponse'
            - type: 'null'
          description: The script run result
        errors:
          anyOf:
            - items:
                additionalProperties: true
                type: object
              type: array
            - type: 'null'
          title: Errors
          description: The errors for the run
        step_count:
          anyOf:
            - type: integer
            - type: 'null'
          title: Step Count
          description: Total number of steps executed in this run
        run_type:
          type: string
          const: workflow_run
          title: Run Type
          description: Type of run - always workflow_run for workflow runs
        attempt:
          type: integer
          title: Attempt
          description: One-based number of the current workflow run attempt
          default: 1
        retry_pending:
          type: boolean
          title: Retry Pending
          description: Whether another attempt is scheduled for this workflow run
          default: false
        next_attempt_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Attempt At
          description: Timestamp when the next workflow run attempt is scheduled
        attempts:
          items:
            $ref: '#/components/schemas/WorkflowRunAttempt'
          type: array
          title: Attempts
          description: Attempts recorded for this workflow run
        run_with:
          type: string
          title: Run With
          description: Whether the workflow run was executed with agent or code
          default: agent
          examples:
            - agent
            - code
        ai_fallback:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Ai Fallback
          description: Whether to fallback to AI if code run fails.
        script_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Script Id
          description: ID of the cached script used for this workflow run, if any.
        browser_seed_source:
          anyOf:
            - $ref: '#/components/schemas/BrowserSeedSource'
            - type: 'null'
          description: >-
            Which layer of the seed-precedence chain seeded this run's browser
            (provenance).
          examples:
            - credential
            - own_memory
            - fresh
        browser_settings_receipt:
          anyOf:
            - $ref: '#/components/schemas/BrowserSettingsReceipt'
            - type: 'null'
          description: >-
            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.
        run_request:
          anyOf:
            - $ref: '#/components/schemas/WorkflowRunRequest-Output'
            - type: 'null'
          description: The original request parameters used to start this workflow run
      type: object
      required:
        - run_id
        - status
        - created_at
        - modified_at
        - run_type
      title: WorkflowRunResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ProxyLocation:
      type: string
      enum:
        - 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
      title: ProxyLocation
    GeoTarget:
      properties:
        country:
          type: string
          maxLength: 2
          minLength: 2
          title: Country
          description: ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
          examples:
            - US
            - GB
            - DE
            - FR
        subdivision:
          anyOf:
            - type: string
              maxLength: 10
            - type: 'null'
          title: Subdivision
          description: >-
            ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for
            California, 'NY' for New York)
          examples:
            - CA
            - NY
            - TX
            - ENG
        city:
          anyOf:
            - type: string
              maxLength: 100
            - type: 'null'
          title: City
          description: >-
            City name in English from GeoNames (e.g., 'New York', 'Los Angeles',
            'London')
          examples:
            - New York
            - Los Angeles
            - London
            - Berlin
        isISP:
          type: boolean
          title: Isisp
          description: Whether this geo target is marked as an ISP proxy location.
          default: false
      type: object
      required:
        - country
      title: GeoTarget
      description: >-
        Granular proxy geo-targeting request with country, optional subdivision,
        and optional city.
    RunStatus:
      type: string
      enum:
        - created
        - queued
        - running
        - paused
        - timed_out
        - failed
        - terminated
        - completed
        - canceled
      title: RunStatus
    FileInfo:
      properties:
        url:
          type: string
          title: Url
          description: URL to access the file
        checksum:
          anyOf:
            - type: string
            - type: 'null'
          title: Checksum
          description: SHA-256 checksum of the file
        filename:
          anyOf:
            - type: string
            - type: 'null'
          title: Filename
          description: Original filename
        file_size:
          anyOf:
            - type: integer
            - type: 'null'
          title: File Size
          description: Size of the file in bytes
        modified_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Modified At
          description: Modified time of the file
        artifact_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Artifact Id
          description: Artifact row id for refresh-on-read
      type: object
      required:
        - url
      title: FileInfo
      description: Information about a downloaded file, including URL and checksum.
    ScriptRunResponse:
      properties:
        ai_fallback_triggered:
          type: boolean
          title: Ai Fallback Triggered
          default: false
        script_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Script Id
        script_revision_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Script Revision Id
      type: object
      title: ScriptRunResponse
    WorkflowRunAttempt:
      properties:
        attempt_number:
          type: integer
          title: Attempt Number
          description: One-based number of this workflow run attempt
        status:
          $ref: '#/components/schemas/RunStatus'
          description: Status of this workflow run attempt
        failure_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Failure Reason
          description: Reason for failure, if the attempt failed
        error_codes:
          items:
            type: string
          type: array
          title: Error Codes
          description: Error codes reported by this attempt
        started_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Started At
          description: Timestamp when this attempt started
        finished_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Finished At
          description: Timestamp when this attempt finished
        retry_decision:
          anyOf:
            - type: string
            - type: 'null'
          title: Retry Decision
          description: Retry decision recorded for this attempt
        decision_reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Decision Reason
          description: Reason recorded for the retry decision
        next_attempt_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Next Attempt At
          description: Timestamp when the next attempt is scheduled
        webhook_sent_at:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Webhook Sent At
          description: Timestamp when the webhook for this attempt was sent
      type: object
      required:
        - attempt_number
        - status
      title: WorkflowRunAttempt
    BrowserSeedSource:
      type: string
      enum:
        - override
        - picked
        - own_memory
        - credential
        - fresh
        - degraded_fresh
      title: BrowserSeedSource
      description: >-
        Which layer of the seed-precedence chain seeded a run's browser
        (provenance).


        Resolved at run setup, before any browser creation, for all run types
        (C-semantics). A

        serialized Save & Reuse run re-resolves once more after the sequential
        wait, so a profile an

        earlier run in its lane saved while it was queued becomes own_memory
        rather than a stale pick.

        - 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
    BrowserSettingsReceipt:
      properties:
        requested_timezone_id:
          type: string
          title: Requested Timezone Id
          description: The timezone that was requested.
        actual_timezone_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Actual Timezone Id
          description: >-
            The timezone the browser reported when measured, or null when it
            could not be measured.
        source:
          $ref: '#/components/schemas/BrowserSettingsSource'
          description: Where the requested setting came from.
        status:
          $ref: '#/components/schemas/BrowserSettingsStatus'
          description: >-
            `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.
        warning:
          anyOf:
            - type: string
            - type: 'null'
          title: Warning
      type: object
      required:
        - requested_timezone_id
        - source
        - status
      title: BrowserSettingsReceipt
    WorkflowRunRequest-Output:
      properties:
        workflow_id:
          type: string
          title: Workflow Id
          description: >-
            ID of the agent to run. Starts with `wpid_`. `workflow_id` is
            accepted as an alias.
          examples:
            - wpid_123
        parameters:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Parameters
          description: Parameters to pass to the workflow
        title:
          anyOf:
            - type: string
            - type: 'null'
          title: Title
          description: The title for this workflow run
        proxy_location:
          anyOf:
            - $ref: '#/components/schemas/ProxyLocation'
            - $ref: '#/components/schemas/GeoTarget'
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Proxy Location
          description: >-

            Geographic Proxy location to route the browser traffic through. This
            is only available in Skyvern Cloud.


            Available geotargeting options:

            - RESIDENTIAL: the default value. Skyvern Cloud uses a random US
            residential proxy.

            - RESIDENTIAL_ES: Spain

            - RESIDENTIAL_IE: Ireland

            - RESIDENTIAL_GB: United Kingdom

            - RESIDENTIAL_IN: India

            - RESIDENTIAL_JP: Japan

            - RESIDENTIAL_FR: France

            - RESIDENTIAL_DE: Germany

            - RESIDENTIAL_NZ: New Zealand

            - RESIDENTIAL_PH: Philippines

            - RESIDENTIAL_KR: South Korea

            - RESIDENTIAL_SA: Saudi Arabia

            - RESIDENTIAL_ZA: South Africa

            - RESIDENTIAL_AR: Argentina

            - RESIDENTIAL_AU: Australia

            - RESIDENTIAL_BR: Brazil

            - RESIDENTIAL_TR: Turkey

            - RESIDENTIAL_CA: Canada

            - RESIDENTIAL_MX: Mexico

            - RESIDENTIAL_IT: Italy

            - RESIDENTIAL_NL: Netherlands

            - RESIDENTIAL_ISP: ISP proxy

            - US-CA: California (deprecated, routes through RESIDENTIAL_ISP)

            - US-NY: New York (deprecated, routes through RESIDENTIAL_ISP)

            - US-TX: Texas (deprecated, routes through RESIDENTIAL_ISP)

            - US-FL: Florida (deprecated, routes through RESIDENTIAL_ISP)

            - US-WA: Washington (deprecated, routes through RESIDENTIAL_ISP)

            - NONE: No proxy


            For self-hosted deployments, you can pass a custom proxy URL as a
            dict: {"url": "http://user:password@proxy.example.com:8080"}. This
            routes the browser through your own proxy server and takes
            precedence over any globally configured proxy pool.
             Can also be a GeoTarget object for granular city/state targeting: {"country": "US", "subdivision": "CA", "city": "San Francisco"}
          default: RESIDENTIAL
        webhook_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Webhook Url
          description: >-
            URL to send workflow status updates to after a run is finished.
            Refer to https://www.skyvern.com/docs/running-tasks/webhooks-faq for
            webhook questions.
        totp_url:
          anyOf:
            - type: string
            - type: 'null'
          title: Totp Url
          description: >

            URL that serves TOTP/2FA/MFA codes for Skyvern to use during the
            workflow run. Refer to
            https://www.skyvern.com/docs/credentials#let-skyvern-fetch-codes-from-your-endpoint
            for more details.
          examples:
            - https://my-totp-service.com/totp
        totp_identifier:
          anyOf:
            - type: string
            - type: 'null'
          title: Totp Identifier
          description: >

            Identifier for the TOTP/2FA/MFA code when the code is pushed to
            Skyvern. Refer to
            https://www.skyvern.com/docs/credentials#push-a-code for more
            details.
          examples:
            - john.doe@example.com
            - '4155555555'
            - user_123
        browser_session_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Session Id
          description: >-
            ID of a Skyvern browser session to reuse, having it continue from
            the current screen state
        reuse_browser_session:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Reuse Browser Session
          description: >-
            Override whether this run reuses the workflow's managed browser
            session. Null inherits the workflow setting. Without login
            credentials, a browser profile key, or a sequential key, reuse is
            workflow-scoped: every run shares one browser and its signed-in
            state, so treat the workflow as single-account.
        browser_profile_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Profile Id
          description: ID of a browser profile to reuse for this workflow run
        start_fresh_browser:
          type: boolean
          title: Start Fresh Browser
          description: >-
            When true, start this run from a fresh, empty browser and ignore any
            saved browser memory — no memory is read or written. A verified
            sign-in during the run still updates the credential's saved login.
          default: false
        max_screenshot_scrolls:
          anyOf:
            - type: integer
            - type: 'null'
          title: Max Screenshot Scrolls
          description: >-
            The maximum number of scrolls for the post action screenshot. When
            it's None or 0, it takes the current viewpoint screenshot.
        max_elapsed_time_minutes:
          anyOf:
            - type: integer
              maximum: 480
              minimum: 1
            - type: 'null'
          title: Max Elapsed Time Minutes
          description: >-
            Timeout this workflow run after the configured elapsed runtime in
            minutes. When omitted, the platform default is 240 minutes. The
            maximum configurable value is 480 minutes.
        extra_http_headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Extra Http Headers
          description: The extra HTTP headers for the requests in browser.
        cdp_connect_headers:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Cdp Connect Headers
          description: >-
            HTTP headers attached ONLY to the CDP WebSocket handshake when
            connecting to a remote browser via browser_address. Use this for
            browser-provider auth (e.g., x-api-key for Skyvern Cloud,
            Browserless, or similar). These headers are NEVER forwarded to
            target websites.
        browser_address:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Address
          description: The CDP address for the workflow run.
          examples:
            - http://127.0.0.1:9222
            - ws://127.0.0.1:9222/devtools/browser/1234567890
        ai_fallback:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Ai Fallback
          description: Whether to fallback to AI if the workflow run fails.
        run_with:
          anyOf:
            - type: string
            - type: 'null'
          title: Run With
          description: >-
            Whether to run the workflow with agent or code. Null inherits from
            the workflow setting.
          examples:
            - agent
            - code
        browser_type:
          anyOf:
            - type: string
            - type: 'null'
          title: Browser Type
          description: >-
            Browser engine for this run, one of the supported browser types
            (e.g. msedge, chrome, stealth-chromium). Overrides the
            workflow-level setting. Null inherits from the workflow.
          examples:
            - chrome
        run_metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Run Metadata
          description: >-
            String key/value metadata to attach to this workflow run for
            analytics tag filtering.
        file_ids:
          anyOf:
            - items:
                type: string
              type: array
              maxItems: 50
            - type: 'null'
          title: File Ids
          description: >

            Ids of files uploaded through `POST /v1/upload_file` to attach to
            this run. Skyvern deletes an attached file as soon as the run
            finishes, so there is nothing to clean up afterwards. Reference an
            attached file by its id anywhere a file URL is accepted (for example
            in `parameters` or in the prompt) and no presigned URL is ever
            created for it. A file can be attached to one run at a time, and
            must not already be deleted.
          examples:
            - - file_123456789
      type: object
      required:
        - workflow_id
      title: WorkflowRunRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    BrowserSettingsSource:
      type: string
      enum:
        - workflow_version
        - session_request
        - existing_session
      title: BrowserSettingsSource
    BrowserSettingsStatus:
      type: string
      enum:
        - verified
        - mismatch
        - unapplied
        - unknown
      title: BrowserSettingsStatus
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      description: Your Skyvern API key from https://app.skyvern.com/settings.
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.