Skip to main content
POST
Start a run

Authorizations

Authorization
string
header
required

API key issued from Settings → API Keys. Pass as Authorization: Bearer <key>.

Query Parameters

version
string

Release or git ref. Defaults to latest.

Minimum string length: 1
wait_for_completion
integer

Seconds to wait before returning (max 600). Omit for async.

Required range: 0 <= x <= 600

Body

Run envelope. Declare provenance with the X-Eigenpal-Trigger header (api or cli). Legacy 0.5.12 body shapes remain accepted.

target
string
required

Automation target without a version suffix, e.g. workflows.invoice or agents.support.

Minimum string length: 1
tags

One exact tag or a list of up to 100 (256 characters each). Tags are returned on the run and in every webhook event as data.run.tags, so use them to carry your own correlation IDs.

Required string length: 1 - 256
input
object

Scalar and structured automation arguments.

files
object

File inputs as ingress references ({ "$fileId": "file_..." } or { "$inline": { filename, mimeType, base64 } }). Upload bytes via multipart files.<fieldName> parts instead.

overrides
object

Per-step output overrides. Workflow runs only.

metadata
object

Caller-supplied run metadata.

Response

Run reached a terminal status while waiting, including failure. Inspect execution.status. Same body as GET /api/v1/runs/:id

tags
string[]
required
id
string
required
type
enum<string>
required
Available options:
workflow,
agent
finished
boolean
required

True when the run has reached a terminal status.

sampleRank
number
required

Deterministic pseudo-random rank in [0, 1) for this run within the tenant. Use with a sample rate threshold to review a stable subset.

Required range: 0 <= x <= 1
timing
object
required
source
object
required
trigger
object
required
execution
object
required

Slim execution metadata always present (status, schemaValid, batchId, retry). Pass expand=execution to replace with full RunExecution (WorkflowRunExecution or AgentRunExecution depending on run type).

parentExecutionId
string

Parent run id when this run was started by an invoke-workflow step. Omitted for top-level runs.

eval
object

Present only on eval-scoped runs. Omitted otherwise.

output
object | null

Completed runs only. Per-automation business result, not a generic schema. Absent until the run completes.

files
object[]

Completed runs only. Download with GET /api/v1/runs/:id/artifacts/:path. Absent until the run completes.

error
object | null

Structured processing failure, independent of the HTTP response status. Includes control.fail statusCode and step when known. Present on terminal runs; null when no error is recorded. Absent while in flight.

input
object

Present only with expand=input.

usage
object | null

Present only with expand=usage. Null for old runs without telemetry.

debug
object

Present only with expand=debug.