Run an orchestration
Start an orchestration and wait for it to finish or pause. response is what the run made: the orchestration's Result key when the run wrote it, otherwise the output of the last step that produced content. A run that pauses on a Human step, or on a tool call its policy wants confirmed, answers paused with the question — answer it with resume. The run keeps going if the client disconnects. See the Orchestrations API.
apiKeyAuthorizationBearer <token>An API key, sk-syn- and 32 characters. On SynapseOrch Cloud an owner or admin makes it under Settings → Developer; on a self-hosted install, under Settings → API Keys.
orch_id*stringThe orchestration's id.
application/json- body
A run's input.
message?stringThe run's input. It is stored in shared state as user_input (and user_query); an Agent or LLM step with no prompt template uses it as its task.
length <= 100000""session_id?|SynapseOrch Cloud only: a conversation id stored with the run, which the runs list returns. A self-hosted install's /api/v1 refuses the field with a 422.
initial_state?Merged into the run's shared state before the first step, so steps read state.<key>. A key that starts with _ is the engine's own and is refused with a 422.
The run's result, or the question it paused on.
application/json- response
status?stringrun_id?stringresponse?stringshared_state?step_history?array<>curl -X POST "https://api.synapseorch.com/api/v1/orchestrations/orch_01a10a0f2d4b6c8e0a1b3c5d7e9f1a2b/run" \ -H "Authorization: Bearer sk-syn-..." \ -H "Content-Type: application/json" \ -d '{ "message": "SynapseOrch platform", "initial_state": { "audience": "engineers" } }'{ "status": "completed", "run_id": "run_orch_k3j9x2a_1734567890123_4f2a9c", "response": "# SynapseOrch platform\n\nSynapseOrch is…", "shared_state": { "user_input": "SynapseOrch platform", "user_query": "SynapseOrch platform", "research": "...", "article": "..." }, "step_history": [ { "step_id": "step_research", "step_name": "Research", "step_type": "agent", "status": "completed", "started_at": "2026-09-16T10:00:00Z", "ended_at": "2026-09-16T10:00:12Z", "duration_seconds": 12.4, "output_key": "research" } ]}{ "status": "paused", "run_id": "run_orch_k3j9x2a_1734567890123_4f2a9c", "human_input_required": { "step_id": "step_approve", "prompt": "Review the draft and approve or reject it.", "fields": [ { "name": "decision", "type": "string", "label": "Decision" } ], "agent_context": "The draft article text…" }}{ "status": "failed", "run_id": "run_orch_k3j9x2a_1734567890123_4f2a9c", "response": "Orchestration failed. Error: TimeoutError: Timed out after 300s", "shared_state": { "...": "..." }, "step_history": [ "..." ]}