# Run a Workflow

## cURL

```bash
curl --request POST \
  --url https://api.skyvern.com/v1/run/workflows \
  --header 'Content-Type: application/json' \
  --data '
{
  "workflow_id": "wpid_123",
  "parameters": {},
  "title": "<string>",
  "proxy_location": "RESIDENTIAL",
  "webhook_url": "<string>",
  "totp_url": "https://my-totp-service.com/totp",
  "totp_identifier": "john.doe@example.com",
  "browser_session_id": "<string>",
  "browser_profile_id": "<string>",
  "max_screenshot_scrolls": 123,
  "extra_http_headers": {},
  "browser_address": "http://127.0.0.1:9222",
  "ai_fallback": true,
  "run_with": "<string>"
}
'
```

### Response Codes

- **200**
- **422**

### Example Response

```json
{
  "run_id": "tsk_123",
  "status": "created",
  "created_at": "2025-01-01T00:00:00Z",
  "modified_at": "2025-01-01T00:05:00Z",
  "run_type": "workflow_run",
  "output": {},
  "downloaded_files": [
    {
      "url": "<string>",
      "checksum": "<string>",
      "filename": "<string>",
      "modified_at": "2023-11-07T05:31:56Z"
    }
  ],
  "recording_url": "<string>",
  "screenshot_urls": [
    "<string>"
  ],
  "failure_reason": "<string>",
  "queued_at": "2023-11-07T05:31:56Z",
  "started_at": "2023-11-07T05:31:56Z",
  "finished_at": "2023-11-07T05:31:56Z",
  "app_url": "https://app.skyvern.com/tasks/tsk_123",
  "browser_session_id": "pbs_123",
  "browser_profile_id": "bp_123",
  "max_screenshot_scrolls": 123,
  "script_run": {
    "ai_fallback_triggered": false,
    "script_id": "<string>",
    "script_revision_id": "<string>"
  },
  "errors": [
    {}
  ],
  "step_count": 123,
  "run_with": "agent",
  "ai_fallback": true,
  "run_request": {
    "workflow_id": "wpid_123",
    "parameters": {},
    "title": "<string>",
    "proxy_location": "RESIDENTIAL",
    "webhook_url": "<string>",
    "totp_url": "https://my-totp-service.com/totp",
    "totp_identifier": "john.doe@example.com",
    "browser_session_id": "<string>",
    "browser_profile_id": "<string>",
    "max_screenshot_scrolls": 123,
    "extra_http_headers": {},
    "browser_address": "http://127.0.0.1:9222",
    "ai_fallback": true,
    "run_with": "<string>"
  }
}
```

## Headers

- **x-api-key**: Skyvern API key for authentication. API key can be found at [https://app.skyvern.com/settings](https://app.skyvern.com/settings).
- **x-max-steps-override**: integer | null
- **x-user-agent**: string | null

## Query Parameters

- **template**: boolean, default: false

## Body
- **workflow_id**: string (required)
  - Example: "wpid_123"
- **parameters**: object  
  - Parameters to pass to the workflow
- **title**: string | null  
  - The title for this workflow run
- **proxy_location**: enum
  - Available options: 
    - RESIDENTIAL
    - RESIDENTIAL_ES
    - RESIDENTIAL_IE
    - RESIDENTIAL_GB
    - RESIDENTIAL_IN
    - RESIDENTIAL_JP
    - RESIDENTIAL_FR
    - RESIDENTIAL_DE
    - RESIDENTIAL_NZ
    - RESIDENTIAL_PH
    - RESIDENTIAL_ZA
    - RESIDENTIAL_AR
    - RESIDENTIAL_AU
    - NONE
- **webhook_url**: string | null
- **totp_url**: string | null
- **totp_identifier**: string | null
- **browser_session_id**: string | null
- **browser_profile_id**: string | null
- **max_screenshot_scrolls**: integer | null
- **extra_http_headers**: object
- **browser_address**: string | null
- **ai_fallback**: boolean | null
- **run_with**: string | null

## Response

### 200: Successfully run workflow
- **run_id**: string (required)
- **status**: enum (required)
  - Available options: created, queued, running, timed_out, failed, terminated, completed, canceled
- **created_at**: string<date-time> (required)
- **modified_at**: string<date-time> (required)
- **run_type**: enum (required)
  - Always workflow_run for workflow runs
- **output**: object
- **downloaded_files**: array | null
- **recording_url**: string | null  
- **screenshot_urls**: array | null
- **failure_reason**: string | null
- **queued_at**: string<date-time> | null
- **started_at**: string<date-time> | null
- **finished_at**: string<date-time> | null
- **app_url**: string | null
- **browser_session_id**: string | null
- **browser_profile_id**: string | null
- **max_screenshot_scrolls**: integer | null
- **script_run**: object
- **errors**: array | null
- **step_count**: integer | null
- **run_with**: string | null
- **ai_fallback**: boolean | null
- **run_request**: object