Runs
Launch a saved version and inspect its durable execution state and outputs
A run executes a snapshot of a saved pipeline version. It records its run ID, project, pipeline version, trigger source, actor and step progress. A queued HTTP/MCP response reports acceptance; it does not report that all steps have completed.
You need a Semogram account with workspace membership, a project in that workspace and permission to create and run pipelines. Reading or writing also requires access to the selected endpoints and external systems. Creating a pipeline does not grant those permissions.
Launch and inspect
Validate the intended draft and commit it first. Inspect the active version and source/destination bindings. For a write, use a dedicated test target until you have verified its behavior.
In Studio, select Run after validation and saving. Open the run to inspect its status, active step, errors, durations, artifacts and connector results.
Show this pipeline’s active version, sources and write targets. After approval, launch it once and retain the run ID. Inspect the completed steps and actual output rather than reporting only that it was queued.Use a workspace API key with pipelines:execute, access to this project and an accountable current member where the operation requires one. Set SEMOGRAM_API_KEY; replace UUID placeholders with actual IDs.
curl --request POST "https://platform.semogram.com/api/v1/projects/<PROJECT_ID_UUID>/pipelines/<PIPELINE_ID_UUID>/execute" \
--header "Authorization: Bearer ${SEMOGRAM_API_KEY}" \
--header "Idempotency-Key: pipeline-demo-operation-001"Send through an authenticated, initialized MCP client. projectId selects the project within the connected workspace.
{
"jsonrpc": "2.0",
"id": 1,
"method": "tools/call",
"params": {
"name": "pipeline_execute",
"arguments": {
"projectId": "<PROJECT_ID_UUID>",
"pipelineId": "<PIPELINE_ID_UUID>",
"idempotencyKey": "pipeline-run-example-001"
}
}
}Read the accepted runId. Poll HTTP GET /api/v1/projects/<PROJECT_ID>/runs/<RUN_ID> (runs:read) or MCP job_get with jobId and projectId. The job survives a client disconnect. Reconnect to inspect the same ID; do not launch a replacement merely because the original response was lost.
Read the result
| Signal | Interpretation |
|---|---|
| Queued | Persisted/accepted; dispatch may still be pending |
| Running | Execution is in progress |
| Completed / succeeded | Execution reached success; verify its actual output |
| Partial | Some work completed with partial results; inspect node diagnostics and output |
| Failed | Inspect the first failing step and any earlier committed effects |
| Cancelled | Work was cancelled; completed effects can remain |
The run detail and connector telemetry can include counts, cursors, snapshots, output artifacts and errors. Interpret counts in the context of the node: a filter can reduce rows; a join can change cardinality; a model result needs business review. Inspect the external target for writes and the persisted assertions/facts for materializers.
A completed run records execution success; it is not human approval of its output. Review produced artifacts and assertions through their own controls. An output review does not turn a run into training data.
Cancel and recover
Use Studio's run controls or MCP pipeline_run_cancel with jobId, optional reason, projectId and an idempotencyKey. No public /api/v1 cancellation action is currently exposed. Cancellation is not rollback of external database/object writes.
Open the run's recovery page to inspect the available recovery action and checkpoint state. A recovery or retry must be appropriate to the connector and original snapshot. Reusing an idempotency key identifies the same API/MCP request; it does not make every downstream append idempotent. Before a retry, compare completed steps, source cursor and actual destination state. For uncertain governed source writes, reconcile the original operation rather than issuing another mutation.
Example operating decision
If ingress read two rows and egress failed after one insert, do not rerun append blindly. Inspect the destination, identify the committed row and choose the supported repair/replay path. A fresh draft cannot change what that failed run already wrote. Preserve its run ID when investigating.
Continue operating
See Monitoring for schedule history and freshness, and Checkpoint recovery for eligibility, retained outputs and the complete reviewed resume flow.