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

# POST /api/workflows/{workflow_id}/run

> Trigger a multi-step Workflow by ID, pass input parameters into the first step, and receive the full run result with per-step output.

`POST /api/workflows/{workflow_id}/run` executes every step of a Workflow in sequence. Inputs flow into the first step and each subsequent step can reference the output of the one before it. The response includes the overall run status, final outputs, credits charged, and a result object for every step.

## Endpoint

```text theme={null}
POST https://api.valendata.com/api/workflows/{workflow_id}/run
```

Replace `{workflow_id}` with the UUID of the Workflow to run. Workflow IDs are plain UUIDs — find them on the Workflows page in the dashboard or via `GET /api/workflows`.

## Authentication

This endpoint requires a session token. Pass your JWT in the `Authorization` header:

```http theme={null}
Authorization: Bearer YOUR_SESSION_TOKEN
```

## Request Body

<ParamField body="inputs" default="{}" type="object">
  A key-value map of input parameters to pass into the first step of the Workflow. Use `{{inputs.field_name}}` syntax inside your step configs to reference these values. Pass an empty object or omit this field entirely if the first step takes no parameters.
</ParamField>

## Example Request

<Tabs>
  <Tab title="cURL">
    ```bash theme={null}
    curl -X POST https://api.valendata.com/api/workflows/3f2a1bc4-e89b-12d3-a456-426614174000/run \
      -H "Authorization: Bearer YOUR_SESSION_TOKEN" \
      -H "Content-Type: application/json" \
      -d '{"inputs": {"target_url": "https://example.com/pricing"}}'
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    import requests

    workflow_id = "3f2a1bc4-e89b-12d3-a456-426614174000"

    response = requests.post(
        f"https://api.valendata.com/api/workflows/{workflow_id}/run",
        headers={"Authorization": "Bearer YOUR_SESSION_TOKEN"},
        json={"inputs": {"target_url": "https://example.com/pricing"}},
    )

    data = response.json()
    print(f"Status: {data['status']}")
    print(f"Credits charged: {data['credits_charged']}")
    print(f"Outputs: {data['outputs']}")
    ```
  </Tab>

  <Tab title="Node.js">
    ```javascript theme={null}
    const workflowId = "3f2a1bc4-e89b-12d3-a456-426614174000";

    const response = await fetch(
      `https://api.valendata.com/api/workflows/${workflowId}/run`,
      {
        method: "POST",
        headers: {
          "Authorization": "Bearer YOUR_SESSION_TOKEN",
          "Content-Type": "application/json",
        },
        body: JSON.stringify({
          inputs: { target_url: "https://example.com/pricing" },
        }),
      }
    );

    const data = await response.json();
    console.log("Status:", data.status);
    console.log("Step results:", data.step_results);
    ```
  </Tab>
</Tabs>

## Response

A successful request returns HTTP `200` with the run result.

### Top-Level Fields

<ResponseField name="id" type="string">
  Unique identifier for this Workflow run (plain UUID).
</ResponseField>

<ResponseField name="workflow_id" type="string">
  The UUID of the Workflow that was executed.
</ResponseField>

<ResponseField name="status" type="string">
  Overall run status. One of `completed`, `failed`, or `waiting_for_human` (when a Human-in-the-Loop step is pending review).
</ResponseField>

<ResponseField name="inputs" type="object | null">
  The inputs that were passed into the first step.
</ResponseField>

<ResponseField name="outputs" type="any | null">
  The output produced by the final step of the Workflow. `null` if the run failed before completing.
</ResponseField>

<ResponseField name="error" type="string | null">
  Error message if the run failed, otherwise `null`.
</ResponseField>

<ResponseField name="credits_charged" type="float">
  Total credits consumed across all steps in this run.
</ResponseField>

<ResponseField name="execution_time_ms" type="integer | null">
  Total wall-clock execution time in milliseconds.
</ResponseField>

<ResponseField name="started_at" type="string | null">
  ISO 8601 UTC timestamp of when execution began.
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  ISO 8601 UTC timestamp of when the run finished.
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 UTC timestamp of when the run record was created.
</ResponseField>

<ResponseField name="step_results" type="array">
  Ordered array of result objects, one per step.

  <Expandable title="Step result fields">
    <ResponseField name="id" type="string">
      UUID of this step result record.
    </ResponseField>

    <ResponseField name="step_id" type="string">
      ID of the step definition within the Workflow.
    </ResponseField>

    <ResponseField name="step_name" type="string">
      Name of the step as configured in the Workflow builder.
    </ResponseField>

    <ResponseField name="step_type" type="string">
      Type of the step: `agent`, `code`, `http`, `transform`, `dfuse`, or `skill`.
    </ResponseField>

    <ResponseField name="sequence_order" type="integer">
      Zero-based position of this step in the Workflow.
    </ResponseField>

    <ResponseField name="status" type="string">
      `completed` or `failed`.
    </ResponseField>

    <ResponseField name="inputs" type="object | null">
      Inputs received by this step.
    </ResponseField>

    <ResponseField name="output" type="any | null">
      Output produced by this step. `null` if it failed.
    </ResponseField>

    <ResponseField name="error" type="string | null">
      Error message if this step failed.
    </ResponseField>

    <ResponseField name="execution_time_ms" type="integer | null">
      Time this step took to run in milliseconds.
    </ResponseField>

    <ResponseField name="started_at" type="string | null">
      ISO 8601 UTC timestamp when this step started.
    </ResponseField>

    <ResponseField name="completed_at" type="string | null">
      ISO 8601 UTC timestamp when this step finished.
    </ResponseField>
  </Expandable>
</ResponseField>

### Example Response

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "workflow_id": "3f2a1bc4-e89b-12d3-a456-426614174000",
  "status": "completed",
  "inputs": { "target_url": "https://example.com/pricing" },
  "outputs": [
    { "plan": "Growth", "price_usd": 45 },
    { "plan": "Pro", "price_usd": 80 }
  ],
  "error": null,
  "credits_charged": 12.5,
  "execution_time_ms": 18400,
  "started_at": "2026-08-20T09:00:00Z",
  "completed_at": "2026-08-20T09:00:18Z",
  "created_at": "2026-08-20T09:00:00Z",
  "step_results": [
    {
      "id": "sr-001",
      "step_id": "step-1",
      "step_name": "Extract Pricing",
      "step_type": "agent",
      "sequence_order": 0,
      "status": "completed",
      "inputs": { "target_url": "https://example.com/pricing" },
      "output": [{ "plan": "Growth", "price_usd": 45 }, { "plan": "Pro", "price_usd": 80 }],
      "error": null,
      "execution_time_ms": 18400,
      "started_at": "2026-08-20T09:00:00Z",
      "completed_at": "2026-08-20T09:00:18Z"
    }
  ]
}
```

## Error Handling

| HTTP Status | Meaning                                                                              |
| :---------- | :----------------------------------------------------------------------------------- |
| `400`       | Bad request — Workflow has no steps, or the request body is malformed.               |
| `401`       | Unauthorized — session token is missing or expired.                                  |
| `404`       | Workflow not found — the `workflow_id` doesn't exist or you don't have access to it. |
| `429`       | Monthly run limit reached — upgrade your plan to continue.                           |
| `500`       | Internal error on Valendata's side.                                                  |