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

# Execute workflow

> POST /api/workflows/{workflowId}/execute to run a published V-Run workflow. Pass JSON inputs or multipart files and receive outputs, cost, and duration.

## Endpoint

```
POST /api/workflows/{workflowId}/execute
```

The endpoint always runs the **latest commit** of the workflow. There is no environment path segment.

## Path parameters

| Parameter    | Type   | Description                            |
| ------------ | ------ | -------------------------------------- |
| `workflowId` | string | The unique identifier of the workflow. |

## Headers

| Header         | Required | Description                                                   |
| -------------- | -------- | ------------------------------------------------------------- |
| `x-api-key`    | Yes      | The workflow's API key.                                       |
| `Content-Type` | Yes      | `application/json` or `multipart/form-data` for file uploads. |

## Request body

A JSON object mapping input names to values. The keys must match the `inputs` declared in the workflow's `config.yaml`.

```json theme={null}
{
  "target_url": "https://example.com",
  "max_articles": 10,
  "include_images": true
}
```

### File uploads

For workflows with `file` or `file_list` inputs, use `multipart/form-data`:

```bash theme={null}
curl -X POST https://run.virtualityhub.com/api/workflows/{workflowId}/execute \
  -H "x-api-key: wk_abc123def456" \
  -F "data_file=@/path/to/data.csv" \
  -F "config={\"format\": \"csv\"}"
```

## Response

### Success (200)

```json theme={null}
{
  "status": "success",
  "executionId": "exec_abc123",
  "duration": 4.2,
  "outputs": {
    "results": "https://run.virtualityhub.com/api/run-logs/exec_abc123/files/results.json"
  },
  "cost": {
    "compute": 0.0042,
    "total": 0.0042
  }
}
```

### Error (401)

```json theme={null}
{
  "error": "Unauthorized",
  "message": "Invalid or missing API key."
}
```

### Error (402)

```json theme={null}
{
  "error": "Insufficient credits",
  "message": "Your account balance is too low. Please top up to continue."
}
```

## Example

<CodeGroup>
  ```python Python theme={null}
  import requests

  response = requests.post(
      "https://run.virtualityhub.com/api/workflows/wf_123/execute",
      headers={
          "x-api-key": "wk_abc123def456",
          "Content-Type": "application/json",
      },
      json={
          "target_url": "https://news.ycombinator.com",
          "max_articles": 5,
      },
  )

  result = response.json()
  print(f"Status: {result['status']}")
  print(f"Cost: ${result['cost']['total']:.4f}")
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    "https://run.virtualityhub.com/api/workflows/wf_123/execute",
    {
      method: "POST",
      headers: {
        "x-api-key": "wk_abc123def456",
        "Content-Type": "application/json",
      },
      body: JSON.stringify({
        target_url: "https://news.ycombinator.com",
        max_articles: 5,
      }),
    }
  );

  const result = await response.json();
  console.log(`Status: ${result.status}`);
  console.log(`Cost: $${result.cost.total.toFixed(4)}`);
  ```
</CodeGroup>