Read a workflow run
Follow a run to a terminal status and collect its assets.
GET {base_url}/workflow-runs/{run_id}
GET {base_url}/workflow-runs/{run_id}?wait=45Requires runs:read.
wait holds the response open for up to that many seconds and returns as soon as the status changes — cheaper than polling, and faster to hear about a finish. Cap is 45 seconds; without it the call returns immediately.
Response
{
"run": {
"id": "0192f3d0-6c31-7a52-b4e8-3f9d1a7c5e20",
"status": "succeeded",
"created_at": "2026-09-22T04:10:00Z",
"completed_at": "2026-09-22T04:17:12Z",
"credits_used": 1792,
"chat_id": "0192f3c6-2e75-7b14-9a63-7c4e2d8f1b09",
"assets": [
{
"id": "0192f3e1-8b52-7c03-a41d-6e2f9b7c1d44",
"kind": "image",
"mime_type": "image/png",
"width": 1920,
"height": 1080,
"size_bytes": 2841233,
"url": "https://storage.googleapis.com/…",
"url_expires_at": "2026-09-22T05:17:12Z"
}
],
"error": null,
"poll_after_seconds": 60
}
}Statuses
status | Meaning | Poll again? |
|---|---|---|
queued | accepted, not started | yes |
running | the workflow is working | yes |
succeeded | finished; assets carries the output | no |
failed | stopped; error says why | no |
needs_input | the workflow asked a question and is waiting for an answer | see below |
expired | never finished before expires_at | no |
Treat any status you do not recognize as non-terminal and keep polling — new ones can arrive without a version bump.
credits_used is what the run has spent so far, net of refunds — present from its first charge, not only once it finishes. A key limited to specific workflows reads a run of any other workflow as not found.
needs_input
Some workflows ask a question mid-run. The run waits for a person in Morphic Studio to answer it; open chat_id to do that. The run resumes on its own once answered, and expires if nobody does before expires_at.
Assets
assets carries only the assets the workflow declares as its output — not every intermediate file its steps produced. What lands here is a decision its authors make in Studio.
| Asset field | Meaning |
|---|---|
id | stable id of the asset in Morphic; safe to store |
kind | image, video, audio or document |
width, height | pixels, for image and video |
duration_seconds | for video and audio |
url | a signed, short-lived download link |
url_expires_at | when that link stops working |
url expires. Download the bytes to your own storage when you receive them; re-read the run to get a fresh link if you need one later. Never store url as if it were permanent.
A succeeded run with an empty assets array means the workflow declares no final output. That is a workflow-authoring gap, not an API failure — ask its authors in Studio to mark which step's output is the deliverable.