---
title: "Flows - Get run status"
method: GET
path: "/v1/ai/flows/runs/{run-id}"
tags: ["flows"]
---

# Flows - Get run status

`GET /v1/ai/flows/runs/{run-id}`

## Request

- Base URL: `https://api.magnific.com`
- URL: `https://api.magnific.com/v1/ai/flows/runs/{run-id}`
- Auth: API key in header `x-magnific-api-key`

Retrieve the current status and results of a flow execution run.

Use this endpoint to **poll** the status of a run after calling the
`POST /v1/ai/flows/{flow-id}/run` endpoint. The `run_id` path parameter
corresponds to the `workflow_run_identifier` returned in the run response.

**Polling strategy:**
- Wait 2-3 seconds after starting the run before the first poll
- Poll every 3-5 seconds
- When `status` is `completed`, the `result` field contains download URLs
- When `status` is `failed`, the `error_message` field describes the failure

**Asset URLs** in the `result` field are temporary and valid for **12 hours**.

**Statuses:**
| Status | Description |
|--------|-------------|
| `pending` | Run is queued but has not started yet |
| `running` | Flow is executing |
| `completed` | Finished successfully, `result` is available |
| `completed_with_errors` | Execution finished but some nodes failed |
| `failed` | Execution failed, see `error_message` |
| `cancelled` | Execution was cancelled |

## Path parameters

- `run-id` string, required

## Response `200`

OK - Run status and result.

- InlineObject9
  - `data` RunDetail, required: Status and result of a single flow execution run.
    - `run_id` string, required: Unique identifier (SQID) for this execution run. Matches the `workflow_run_identifier` returned by the run endpoint.
    - `status` 'pending' | 'running' | 'completed' | 'completed_with_errors' | 'failed' | 'cancelled', required: Execution status of the flow run: - `pending`: Run is queued but has not started yet - `running`: Flow is executing - `completed`: Finished successfully, result is available - `completed_with_errors`: Execution finished but some nodes failed - `failed`: Execution failed entirely - `cancelled`: Execution was cancelled
    - `app_id` string, required: SQID of the flow that was executed. (Field name retained from the underlying execution payload.)
    - `started_at` string, date-time, nullable, required: ISO 8601 timestamp when execution started. Null while the run is pending.
    - `completed_at` string, date-time, nullable, required: ISO 8601 timestamp when execution completed. Null while the run is still in progress.
    - `error_message` string, nullable, required: Error details when the execution fails or completes with errors. Null on success.
    - `result` RunDetailResult, nullable, required: Execution output. Contains arrays of generated assets grouped by media type. Null while the run is still in progress or if the execution failed. Asset URLs are **temporary** and valid for 12 hours.
      - `images` WebhookResultItem[]: Generated image assets.
        - `id` string: Unique identifier of the generated asset.
        - `url` string, uri: Download URL for the generated asset.
        - `tool` string: The AI tool that produced this asset (e.g. `text-to-image`, `image-upscaler`).
        - `duration` number, nullable: Duration in seconds (for video/audio assets). Null for images.
        - `width` integer, nullable: Width in pixels.
        - `height` integer, nullable: Height in pixels.
        - `created_at` string, date-time: ISO 8601 creation timestamp of the asset.
      - `videos` WebhookResultItem[]: Generated video assets.
        - `id` string: Unique identifier of the generated asset.
        - `url` string, uri: Download URL for the generated asset.
        - `tool` string: The AI tool that produced this asset (e.g. `text-to-image`, `image-upscaler`).
        - `duration` number, nullable: Duration in seconds (for video/audio assets). Null for images.
        - `width` integer, nullable: Width in pixels.
        - `height` integer, nullable: Height in pixels.
        - `created_at` string, date-time: ISO 8601 creation timestamp of the asset.
      - `audios` WebhookResultItem[]: Generated audio assets.
        - `id` string: Unique identifier of the generated asset.
        - `url` string, uri: Download URL for the generated asset.
        - `tool` string: The AI tool that produced this asset (e.g. `text-to-image`, `image-upscaler`).
        - `duration` number, nullable: Duration in seconds (for video/audio assets). Null for images.
        - `width` integer, nullable: Width in pixels.
        - `height` integer, nullable: Height in pixels.
        - `created_at` string, date-time: ISO 8601 creation timestamp of the asset.

## Other responses

- `401`: Unauthorized - The client must authenticate itself to get the requested response.
- `403`: Forbidden - The client does not have permission to access the requested resource.
- `404`: Not Found - The server can not find the requested resource.
- `500`: Internal Server Error - The server has encountered a situation it doesn't know how to handle.
- `503`: Service Unavailable

---

[API](https://skmtc.dev/magnific/apis/magnific-api.md) · [All operations](https://skmtc.dev/magnific/apis/magnific-api/llms.txt) · [OpenAPI document](https://skmtc.dev/magnific/apis/magnific-api/revisions/60711fb082c7?raw)