Sign in
Agents

Login Task

Log in to a website using either credential stored in Skyvern, Bitwarden, 1Password, or Azure Vault

post/v1/run/tasks/login

Headers

x-api-keystring nullable
x-user-agentstring nullable

Request body

urlstring nullable

Website URL

webhook_urlstring nullable

Webhook URL to send status updates

proxy_location'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'
totp_identifierstring nullable

Identifier for TOTP (Time-based One-Time Password) if required

totp_urlstring nullable

TOTP URL to fetch one-time passwords

browser_session_idstring nullable

ID of the browser session to use, which is prefixed by pbs_ e.g. pbs_123456

browser_profile_idstring nullable

ID of a browser profile to reuse for this run

start_fresh_browserboolean

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.

browser_addressstring nullable

The CDP address for the task.

extra_http_headersobject nullable

Additional HTTP headers to include in requests

cdp_connect_headersobject nullable

HTTP headers attached ONLY to the CDP WebSocket handshake when connecting to a remote browser via browser_address. Never forwarded to target websites.

max_screenshot_scrolling_timesinteger nullable

Maximum number of times to scroll for screenshots

credential_type'skyvern' | 'bitwarden' | '1password' | 'azure_vault' required
promptstring nullable

Login instructions. Skyvern has default prompt/instruction for login if this field is not provided.

credential_idstring nullable

ID of the Skyvern credential to use for login.

bitwarden_collection_idstring nullable

Bitwarden collection ID. You can find it in the Bitwarden collection URL. e.g. https://vault.bitwarden.com/vaults/collection_id/items

bitwarden_item_idstring nullable

Bitwarden item ID

onepassword_vault_idstring nullable

1Password vault ID

onepassword_item_idstring nullable

1Password item ID

onepassword_totp_field_namestring nullable

1Password item field id or label to treat as the TOTP secret, overriding 1Password's own field-type detection

azure_vault_namestring nullable

Azure Vault Name

azure_vault_username_keystring nullable

Azure Vault username key

azure_vault_password_keystring nullable

Azure Vault password key

azure_vault_totp_secret_keystring nullable

Azure Vault TOTP secret key

Example request

{
  "browser_session_id": "pbs_123456",
  "browser_address": "http://127.0.0.1:9222",
  "credential_id": "cred_123"
}

Response

Successful Response

run_idstring required

Unique identifier for this run. Run ID starts with tsk_ for task runs and wr_ for workflow runs.

status'created' | 'queued' | 'running' | 'paused' | 'timed_out' | 'failed' | 'terminated' | 'completed' | 'canceled' required
recording_urlstring nullable

URL to the recording of the run

recording_archivedboolean

True when the recording exists but has been archived to cold storage and is not currently accessible.

screenshot_urlsstring[] nullable

List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.

failure_reasonstring nullable

Reason for failure if the run failed or terminated

created_atstring date-time required

Timestamp when this run was created

modified_atstring date-time required

Timestamp when this run was last modified

queued_atstring date-time nullable

Timestamp when this run was queued

started_atstring date-time nullable

Timestamp when this run started execution

finished_atstring date-time nullable

Timestamp when this run finished

app_urlstring nullable

URL to the application UI where the run can be viewed

browser_session_idstring nullable

ID of the Skyvern persistent browser session used for this run

browser_profile_idstring nullable

ID of the browser profile used for this run

max_screenshot_scrollsinteger nullable

The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot

errorsobject[] nullable

The errors for the run

step_countinteger nullable

Total number of steps executed in this run

run_type'workflow_run' required

Type of run - always workflow_run for workflow runs

run_withstring

Whether the workflow run was executed with agent or code

ai_fallbackboolean nullable

Whether to fallback to AI if code run fails.

script_idstring nullable

ID of the cached script used for this workflow run, if any.

browser_seed_source'override' | 'picked' | 'own_memory' | 'credential' | 'fresh' | 'degraded_fresh'

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

Example response

{
  "run_id": "tsk_123",
  "created_at": "2025-01-01T00:00:00Z",
  "modified_at": "2025-01-01T00:05:00Z",
  "app_url": "https://app.skyvern.com/tasks/tsk_123",
  "browser_session_id": "pbs_123",
  "browser_profile_id": "bp_123",
  "run_with": "agent",
  "run_request": {
    "workflow_id": "wpid_123",
    "proxy_location": {
      "country": "US",
      "subdivision": "CA",
      "city": "New York"
    },
    "totp_url": "https://my-totp-service.com/totp",
    "totp_identifier": "john.doe@example.com",
    "browser_address": "http://127.0.0.1:9222",
    "run_with": "agent",
    "file_ids": [
      "file_123456789"
    ]
  }
}

Changes

Changed in 10 of the 86 revisions of this API.661746

  • 6aafd1417ba51See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

  • 89037b86e0041See the full diff
    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • 830020b643cd1See the full diff
    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • bd64e0480f0a3See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

  • b7fa64d357691See the full diff
    • ●

      added the new paused enum value to the response property for the response status

      response-property-enum-value-added

  • cd89b4c6f0041See the full diff
    • ▲

      the /// response property's max was increased from 240.00 to 480.00 for the response status

      response-property-max-increased

  • 3a3616091b66651636See the full diff
    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      the request property became not nullable

      request-property-became-not-nullable

    • ▲

      removed the enum value NONE of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_AR of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_AU of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_BR of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_CA of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_DE of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_ES of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_FR of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_GB of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_IE of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_IN of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_ISP of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_IT of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_JP of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_MX of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_NL of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_NZ of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_PH of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_TR of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value RESIDENTIAL_ZA of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value US-CA of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value US-FL of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value US-NY of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value US-TX of the request property

      request-property-enum-value-removed

    • ▲

      removed the enum value US-WA of the request property

      request-property-enum-value-removed

    • ▲

      the request property type changed from string to no type

      request-property-type-changed

    • ▲

      response property ai_fallback list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property app_url list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property browser_profile_id list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property browser_session_id list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property downloaded_files list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property errors list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property failure_reason list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property finished_at list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property max_screenshot_scrolls list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property output list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property queued_at list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property recording_url list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property screenshot_urls list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property started_at list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      response property step_count list-of-types was widened by adding types null to media type application/json of response 200

      response-property-list-of-types-widened

    • ▲

      the response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      the response's property type changed from object to no type for status

      response-property-type-changed

    • ▲

      removed the required property / from the response with the status

      response-required-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ●

      removed the optional property / from the response with the status

      response-optional-property-removed

    • ○

      api tag Agents added

      api-tag-added

    • ○

      api tag Agent removed

      api-tag-removed

    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      header request parameter x-api-key list-of-types was widened by adding types null

      request-parameter-list-of-types-widened

    • ○

      header request parameter x-user-agent list-of-types was widened by adding types null

      request-parameter-list-of-types-widened

    • ○

      for the header request parameter x-api-key, the type was generalized from string to no type

      request-parameter-type-generalized

    • ○

      for the header request parameter x-user-agent, the type was generalized from string to no type

      request-parameter-type-generalized

    • ○

      added subschema #2 to the request property anyOf list

      request-property-any-of-added

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      request property list-of-types was widened by adding types null to media type application/json

      request-property-list-of-types-widened

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property // to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added the optional property to the response with the status

      response-optional-property-added

    • ○

      added subschema #2 to the response property anyOf list for the response status

      response-property-any-of-added

    • ○

      added subschema #2 to the response property anyOf list for the response status

      response-property-any-of-added

    • ○

      the response property const value workflow_run was added for the status

      response-property-const-added

    • ○

      the response's property default value agent was added for the status

      response-property-default-value-added

    • ○

      removed the workflow_run enum value from the response property for the response status

      response-property-enum-value-removed

    This revision also has 10 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 4e8048e3afda1See the full diff
    • ○

      added the new optional header request parameter x-user-agent

      new-optional-request-parameter

  • 3b8ad911785b2See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • a8899e7707c41See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 5 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog