POST /api/workflows/{workflow_id}/run

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

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:

Authorization: Bearer YOUR_SESSION_TOKEN

Request Body

object

default:"{}"

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.

Example Request

cURL
Python
Node.js

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"}}'

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']}")

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);

Response

A successful request returns HTTP 200 with the run result.

Top-Level Fields

string

Unique identifier for this Workflow run (plain UUID).

string

The UUID of the Workflow that was executed.

string

Overall run status. One of completed, failed, or waiting_for_human (when a Human-in-the-Loop step is pending review).

object | null

The inputs that were passed into the first step.

any | null

The output produced by the final step of the Workflow. null if the run failed before completing.

string | null

Error message if the run failed, otherwise null.

float

Total credits consumed across all steps in this run.

integer | null

Total wall-clock execution time in milliseconds.

string | null

ISO 8601 UTC timestamp of when execution began.

string | null

ISO 8601 UTC timestamp of when the run finished.

string

ISO 8601 UTC timestamp of when the run record was created.

array

Ordered array of result objects, one per step.

Show Step result fields

string

UUID of this step result record.

string

ID of the step definition within the Workflow.

string

Name of the step as configured in the Workflow builder.

string

Type of the step: agent, code, http, transform, dfuse, or skill.

integer

Zero-based position of this step in the Workflow.

string

completed or failed.

object | null

Inputs received by this step.

any | null

Output produced by this step. null if it failed.

string | null

Error message if this step failed.

integer | null

Time this step took to run in milliseconds.

string | null

ISO 8601 UTC timestamp when this step started.

string | null

ISO 8601 UTC timestamp when this step finished.

Example Response

{
  "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.

Overview

Skills

Workflows

Runs

POST /api/workflows/{workflow_id}/run

Endpoint

Authentication

Request Body

Example Request

Response

Top-Level Fields

Example Response

Error Handling

​Endpoint

​Authentication

​Request Body

​Example Request

​Response

​Top-Level Fields

​Example Response

​Error Handling

Endpoint

Authentication

Request Body

Example Request

Response

Top-Level Fields

Example Response

Error Handling