---
title: "Login Task"
method: POST
path: "/v1/run/tasks/login"
tags: ["Agents"]
---

# Login Task

`POST /v1/run/tasks/login`

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

## Headers

- `x-api-key` string, nullable
- `x-user-agent` string, nullable

## Request body

- LoginRequest
  - `url` string, nullable — Website URL
  - `webhook_url` string, 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_identifier` string, nullable — Identifier for TOTP (Time-based One-Time Password) if required
  - `totp_url` string, nullable — TOTP URL to fetch one-time passwords
  - `browser_session_id` string, nullable — ID of the browser session to use, which is prefixed by `pbs_` e.g. `pbs_123456`
  - `browser_profile_id` string, nullable — ID of a browser profile to reuse for this run
  - `start_fresh_browser` boolean — 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_address` string, nullable — The CDP address for the task.
  - `extra_http_headers` object, nullable — Additional HTTP headers to include in requests
  - `cdp_connect_headers` object, 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_times` integer, nullable — Maximum number of times to scroll for screenshots
  - `credential_type` 'skyvern' | 'bitwarden' | '1password' | 'azure_vault', required
  - `prompt` string, nullable — Login instructions. Skyvern has default prompt/instruction for login if this field is not provided.
  - `credential_id` string, nullable — ID of the Skyvern credential to use for login.
  - `bitwarden_collection_id` string, 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_id` string, nullable — Bitwarden item ID
  - `onepassword_vault_id` string, nullable — 1Password vault ID
  - `onepassword_item_id` string, nullable — 1Password item ID
  - `azure_vault_name` string, nullable — Azure Vault Name
  - `azure_vault_username_key` string, nullable — Azure Vault username key
  - `azure_vault_password_key` string, nullable — Azure Vault password key
  - `azure_vault_totp_secret_key` string, nullable — Azure Vault TOTP secret key

## Response `200`

Successful Response

- WorkflowRunResponse
  - `run_id` string, 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
  - `output` union — Output data from the run, if any. Format/schema depends on the data extracted by the run.
    - object
    - unknown[]
      - unknown
    - string
  - `downloaded_files` FileInfo[], nullable — List of files downloaded during the run
    - `url` string, required — URL to access the file
    - `checksum` string, nullable — SHA-256 checksum of the file
    - `filename` string, nullable — Original filename
    - `file_size` integer, nullable — Size of the file in bytes
    - `modified_at` string, date-time, nullable — Modified time of the file
    - `artifact_id` string, nullable — Artifact row id for refresh-on-read
  - `recording_url` string, nullable — URL to the recording of the run
  - `recording_archived` boolean — True when the recording exists but has been archived to cold storage and is not currently accessible.
  - `screenshot_urls` string[], nullable — List of last n screenshot URLs in reverse chronological order - the first one the list is the latest screenshot.
  - `failure_reason` string, nullable — Reason for failure if the run failed or terminated
  - `created_at` string, date-time, required — Timestamp when this run was created
  - `modified_at` string, date-time, required — Timestamp when this run was last modified
  - `queued_at` string, date-time, nullable — Timestamp when this run was queued
  - `started_at` string, date-time, nullable — Timestamp when this run started execution
  - `finished_at` string, date-time, nullable — Timestamp when this run finished
  - `app_url` string, nullable — URL to the application UI where the run can be viewed
  - `browser_session_id` string, nullable — ID of the Skyvern persistent browser session used for this run
  - `browser_profile_id` string, nullable — ID of the browser profile used for this run
  - `max_screenshot_scrolls` integer, nullable — The maximum number of scrolls for the post action screenshot. When it's None or 0, it takes the current viewpoint screenshot
  - `script_run` ScriptRunResponse
    - `ai_fallback_triggered` boolean
    - `script_id` string, nullable
    - `script_revision_id` string, nullable
  - `errors` object[], nullable — The errors for the run
  - `step_count` integer, nullable — Total number of steps executed in this run
  - `run_type` 'workflow_run', required — Type of run - always workflow_run for workflow runs
  - `run_with` string — Whether the workflow run was executed with agent or code
  - `ai_fallback` boolean, nullable — Whether to fallback to AI if code run fails.
  - `script_id` string, 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
  - `run_request` WorkflowRunRequestOutput
    - `workflow_id` string, required — ID of the agent to run. Starts with `wpid_`. `workflow_id` is accepted as an alias.
    - `parameters` object, nullable — Parameters to pass to the workflow
    - `title` string, nullable — The title for this workflow run
    - `proxy_location` union — 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"}
      - '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'
      - GeoTarget — Granular proxy geo-targeting request with country, optional subdivision, and optional city.
        - `country` string, required — ISO 3166-1 alpha-2 country code (e.g., 'US', 'GB', 'DE')
        - `subdivision` string, nullable — ISO 3166-2 subdivision code without country prefix (e.g., 'CA' for California, 'NY' for New York)
        - `city` string, nullable — City name in English from GeoNames (e.g., 'New York', 'Los Angeles', 'London')
      - object
    - `webhook_url` string, nullable — 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` string, nullable — URL that serves TOTP/2FA/MFA codes for Skyvern to use during the workflow run. Refer to https://www.skyvern.com/docs/credentials/totp#option-2-get-code-from-your-endpoint for more details.
    - `totp_identifier` string, nullable — Identifier for the TOTP/2FA/MFA code when the code is pushed to Skyvern. Refer to https://www.skyvern.com/docs/credentials/totp#option-3-push-code-to-skyvern for more details.
    - `browser_session_id` string, nullable — ID of a Skyvern browser session to reuse, having it continue from the current screen state
    - `reuse_browser_session` boolean, nullable — 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` string, nullable — ID of a browser profile to reuse for this workflow run
    - `start_fresh_browser` boolean — 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.
    - `max_screenshot_scrolls` integer, nullable — 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` integer, nullable — 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` object, nullable — The extra HTTP headers for the requests in browser.
    - `cdp_connect_headers` object, nullable — 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` string, nullable — The CDP address for the workflow run.
    - `ai_fallback` boolean, nullable — Whether to fallback to AI if the workflow run fails.
    - `run_with` string, nullable — Whether to run the workflow with agent or code. Null inherits from the workflow setting.
    - `run_metadata` object, nullable — String key/value metadata to attach to this workflow run for analytics tag filtering.
    - `file_ids` string[], nullable — 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.

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/skyvern-ai/apis/skyvern-api-2.md) · [All operations](https://skmtc.net/skyvern-ai/apis/skyvern-api-2/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/skyvern-ai/skyvern-api-2/revisions/6d5b02ddd6fe/schema)