Runs

A run is a single execution of a workflow version in a stage, backed by an Argo Workflow. Runs are the record of what executed, when, and with what result — essential for monitoring, debugging, and auditing.

Triggering a Run

versionId and stage are supplied as query parameters; stage always selects the execution environment:

POST .../workflows/ml-training-pipeline/runs?versionId=1.0.0&stage=prod

For the normal production path — where a version and configuration are already bound to the stage — no request body is needed. The API resolves every ${config.KEY} reference, submits the workflow to Argo, and returns the run.

Configuration Resolution at Run Time

If the version's task arguments contain ${config.KEY} references, the API resolves them at run creation by merging up to three sources per key, highest priority first:

1. Inline configuration — an ad-hoc key/value map in the request body (one-off tests / overrides; nothing persisted).
2. Inline configurationId — a reference to a saved configuration, in the request body.
3. Stage-bound configurationId — from the stage assignment (the normal production path).

Because the merge is per key, an inline source can override a single key while the rest fall back to the stage-bound configuration. For example, with prod-config bound to the stage:

// POST .../runs?versionId=1.0.0&stage=prod
{ "configuration": { "LOG_LEVEL": "DEBUG" } }

overrides only LOG_LEVEL and resolves all other keys from prod-config.

Triggers use stage config only

Webhook and schedule triggers always use the stage-bound configuration — they cannot pass inline configuration.

Unresolved References

If any ${config.KEY} remains unresolved after merging, the run is rejected:

// HTTP 422 Unprocessable Entity
{
  "detail": [
    { "msg": "Unresolved configuration reference: ${config.BUCKET}" }
  ]
}

Audit Snapshot

Every run stores the exact values it used in resolvedConfiguration, so you can always see which parameters produced a given historical run — even though configurations are mutable:

{
  "runId": "ml-training-pipeline-xyz123",
  "stage": "prod",
  "versionId": "1.0.0",
  "configurationId": "prod-config",
  "resolvedConfiguration": { "BUCKET": "prod-bucket", "RAY_REPLICAS": "4" },
  "status": "Running"
}

Monitoring and Managing Runs

• List / filter runs by status, versionId, and stage, with cursor-based pagination.
• Get a single run to read its live status, timestamps, and per-task breakdown.
• Cancel a running workflow (idempotent — a terminal run is returned unchanged).
• Retry the failed tasks of a Failed run while preserving completed task results.

Run creation and retry accept an optional Idempotency-Key header to de-duplicate submissions.

Reference

See the full endpoint contract in the CAIP Workflows API Reference.