Pipeline Execution API

Execute a saved pipeline with custom input data.

Endpoint: POST /api/v1/pipelines/{pipelineId}/run Required permission: pipelines

Request


curl -X POST https://forgejson.com/api/v1/pipelines/jp7abc123/run \
  -H "Authorization: Bearer fje_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "default": {
        "name": "Alice",
        "age": 25,
        "tags": ["admin", "active"]
      }
    },
    "verbose": true
  }'

Request body


{
  "inputs": {
    "<input-node-name>": <any JSON value>
  },
  "verbose": true
}

Field	Type	Required	Description
`inputs`	object	No	Named input values matched to pipeline input nodes
`verbose`	boolean	No	Include `stepOutputs` in the response when `true`

If the pipeline has one input node and you send exactly one input key, that value is used even if the key does not match the node name exactly. For pipelines with multiple input nodes, keys should match sanitized input node names.

Response (200) — Success


{
  "success": true,
  "output": {
    "name": "ALICE",
    "age": 25,
    "tags": ["ADMIN", "ACTIVE"],
    "fullName": "ALICE"
  },
  "stepOutputs": {
    "step-1-abc": { "name": "ALICE", "age": 25, "tags": ["ADMIN", "ACTIVE"] },
    "step-2-def": { "name": "ALICE", "age": 25, "tags": ["ADMIN", "ACTIVE"], "fullName": "ALICE" }
  },
  "durationMs": 42,
  "creditsUsed": 1
}

Field	Type	Description
`output`	any JSON	The final result after all pipeline steps
`stepOutputs`	object	Output from each individual step, keyed by step ID. Returned only when `verbose` is `true`.
`durationMs`	number	Execution time in milliseconds
`creditsUsed`	number	Credits consumed (1 per successful run)

Response (400) — Pipeline failure


{
  "success": false,
  "error": "Pipeline produced no output"
}

Field	Type	Description
`error`	string	Description of what went wrong

Size limits

Limit	Value
Maximum payload size	50 MB
Worker threshold	Payloads > 2 KB run in a worker thread
Worker timeout	30 seconds

Large payloads (> 2 KB) are executed in a worker thread with a 30-second timeout. If your pipeline processes very large documents, consider breaking the work into smaller chunks.

Error responses

Status	Meaning
`400`	Pipeline execution failed, malformed input
`401`	Authentication failed
`403`	Missing `pipelines` permission
`404`	Pipeline not found
`408`	Execution timed out (30s for worker)
`413`	Payload exceeds 50 MB
`429`	Rate limit exceeded
`500`	Internal server error

How pipelines are resolved

When you call this endpoint:

The pipeline definition is loaded from Convex (nodes, edges, step configurations)
Your inputs object is matched against the pipeline input nodes
Steps are executed in topological order based on connections
Each step’s output feeds into downstream steps
The last step’s output becomes the output field in the response

The pipeline must be saved and owned by the same account as the API key. You cannot execute another user’s pipeline.