---
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 — Skyvern API key for authentication. API key can be found at https://app.skyvern.com/settings.
- `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
  - `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.
  - `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
    - `browser_profile_id` string, nullable — ID of a browser profile to reuse for this workflow 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.
    - `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.

## Other responses

- `422` — Validation Error

---

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