Create and trigger a workflow run

post

https://api2.pennsieve.io/compute/workflows/runs

Primary endpoint: create + trigger a run. Provide either workflowInstanceId
(existing config) or workflowInstanceConfiguration (find-or-create config).

Recent Requests

Time	Status	User Agent
Retrieving recent requests…

Loading…

Body Params

Run request payload

workflowInstanceId

string

UUID of an existing workflow instance config (mode 1)

workflowInstanceConfiguration

object

Inline config for find-or-create (mode 2)

name

string

Optional human-friendly label for the run. When omitted, workflow-service generates a default of "run-

datasetId

string

dataSources

object

Structured data-source inputs keyed by data-source node ID. Each entry must match a data-source node in the workflow definition.

dataTargets

object

Per-data-target inputs keyed by data-target node ID. The user provides per-run values (e.g. folder). The system enriches each entry with registry params (e.g. uploadBucket).

processorParams

object

Per-processor runtime parameters keyed by processor node ID.

tags

object

Per-run image tag/version overrides keyed by processor node ID. Applied to a copy of the workflow's DAG snapshot before the run is persisted; the source workflow definition is not mutated. Useful for pinning a specific version for one run, or supplying a tag for legacy workflow snapshots that predate the tag requirement.

layers

array of strings

Persistent layer names to mount for this execution. Layers must exist with status READY on the compute node.

layers

completionCallbackUrl

string

Optional. When set, workflow-service POSTs a webhook to this URL on terminal status (SUCCEEDED | FAILED | CANCELED) so the triggering caller can react to completion without polling. v1 contract: must be a Lambda Function URL with AWS_IAM auth; workflow-service signs the POST with SigV4 using its execution role. Generic by design — any service, UI, or processor that triggers a run can register a hook.

completionCallbackContext

object

Optional, opaque to workflow-service. Whatever the caller stashes here is echoed back verbatim in the webhook body on terminal status. Typical contents: a WebSocket connection ID, a conversation/correlation ID, an originating request UUID — anything the caller needs to route the completion event.

maxCostUsd

double

Optional per-execution LLM cost cap (USD). When set, workflow-service forwards it to compute-gateway-v2 on the workflow-init request body; compute-gateway-v2 persists it on the Step Functions input; the llm-governor-proxy sidecar attached to each processor task enforces it as executionBudgetUsd on every Bedrock call made during the run.
Zero/omitted means no caller-side cap (the governor still enforces its own per-node ceilings independently). chat-service populates this when a workflow is triggered through an MCP tool, derived from the user's resolved per-user-per-node quota.

Responses

503

Spend limits or recorded spend could not be read, so the run was
denied. The gate fails closed: on a shared compute node it is the
only control between open access and the AWS bill.

200The run was successfully triggered

402Pipeline spend cap reached on this compute node. Distinct from 403 so the caller can tell "you cannot use this node" apart from "you have used up this period's allowance".

403Forbidden. Possible reasons: user lacks access to compute node, or workflow contains processor source URLs not in the compute node's allowed processors whitelist.

4XXIncorrect authentication or user has incorrect permissions.

5XXServer Error