---
title: Floyo API - Workflow Runs
slug: floyo-api-workflow-runs
docTags: 
createdAt: 2026-04-27T18:58:27.200Z
---

# Introduction

A `run` represents a **workflow run**. You can easily create new runs, cancel any active run and retrieve a run details from the `/runs` resource.



***

# Create a run

To create a `run` make an authenticated `POST` request to `/runs`.


**BODY JSON PAYLOAD**

| Parameter  | Required | Type     | Description                                                                                                             |
| ---------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------- |
| `workflow` | Yes      | `JSON`   | A Comfy API workflow JSON                                                                                               |
| `name`     | No       | `string` | Optional workflow run name. If none provided the run name will be set to the default name `API Run YYYY-MM-DD HH:mm:ss` |



**EXAMPLE REQUEST:**

:::CodeblockTabs
cURL

```curl
curl -X POST https://api.floyo.ai/runs \
     -H "Authorization: Bearer <YOUR_API_KEY>" \
     -H "Accept: application/json" \  
     --json '{    
       "name": "Floyo API Demo run",
       "workflow": { ...WORKFLOW API JSON... }    
     }'
```
:::

**EXAMPLE RESPONSES:**

`STATUS 200`: **Workflow run requested successfully.**

```json
{    
   "id": "run_vTGqfqzFotmivzRP",
   "object": "run",
   "name": "Floyo API Demo run"
 }
```

If the request results in a `4xx` or `5xx` error, see the [Error Responses](docId\:W37qHjsl3Ldxxz-dYsZd_) section.

***



# Cancel a run

To cancel an active `run` you must make an **authenticated&#x20;**`POST` request to `/runs/<RUN_ID>/cancel`.

A `run` can be canceled only if its current `status` is either in `queued`or `running`.



**EXAMPLE REQUEST:**

:::CodeblockTabs
cURL

```curl
curl -X POST https://api.floyo.ai/runs/<RUN_ID>/cancel \  
     -H "Authorization: Bearer <YOUR_API_KEY>" \  
     -H "Accept: application/json"`
```
:::

****

**EXAMPLE RESPONSE:**

`STATUS 200`: Run successfully canceled.

```json
{
  "id": "run_C7d3eSgnVhj1A6Ts",
  "object": "run",
  "message": "Run canceled"
}
```


`STATUS 409`: Run was canceled, has finished or failed.

```json
{
  "id": "run_C7d3eSgnVhj1A6Ts",
  "status": "canceled",
  "object": "run",
  "error": "Run is already finished",
  "message": "Run was canceled by the user"
}
```



`STATUS 404`: Run not found.

```json
{ "error": "Run not found" }
```



***



# List runs

List runs returns a paginated collection of workflow runs for your team. Use query parameters to filter, search, sort, and expand each run in the response. Pass the `cursor` from a previous response to fetch the next page when `has_more` is `true`.

To list runs, make an authenticated `GET` request to `/runs`.

QUERY PARAMETERS:

| Parameter                     | Required | Value                                                                                                             | Default                        | Description                                                                                                                                                                                                                                                                 | Example                                                                                |
| ----------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `search`                      | No       | `string` (3–128 characters)                                                                                       | N/A                            | Case-insensitive search against the run name or the username/email of the user who triggered the run.                                                                                                                                                                       | `/runs?search=flux`                                                                    |
| `status`                      | No       | `queued`,<br />`running`,<br />`complete`, `failed` or`canceled`(comma-separated)                                 | N/A                            | Filter runs by one or more statuses.                                                                                                                                                                                                                                        | `/runs?status=complete,failed`                                                         |
| `requested_at[gte]`           | No       | ISO 8601 datetime or UNIX timestamp in seconds                                                                    | N/A                            | Include runs requested at or after this timestamp.                                                                                                                                                                                                                          | `/runs?requested_at[gte]=1777593599`                                                   |
| `requested_at[lte]`           | No       | ISO 8601 datetime or UNIX timestamp in seconds                                                                    | N/A                            | Include runs requested at or before this timestamp. Must be greater than or equal to `requested_at[gte]` when both are set.                                                                                                                                                 | `/runs?requested_at[lte]=2026-04-30T23:59:59Z`                                         |
| `flotime_ms[gte]`             | No       | integer ≥ 0                                                                                                       | N/A                            | Include runs whose FloTime usage is greater than or equal to this value, in milliseconds.                                                                                                                                                                                   | `/runs?flotime_ms[gte]=1000`                                                           |
| `flotime_ms[lte]`             | No       | integer ≥ 0                                                                                                       | N/A                            | Include runs whose FloTime usage is less than or equal to this value, in milliseconds. Must be greater than or equal to `flotime_ms[gte]` when both are set.                                                                                                                | `/runs?flotime_ms[lte]=60000`                                                          |
| `partner_nodes_cost_usd[gte]` | No       | number ≥ 0                                                                                                        | N/A                            | Include runs whose Partner Nodes cost is greater than or equal to this USD amount.                                                                                                                                                                                          | `/runs?partner_nodes_cost_usd[gte]=0.01`                                               |
| `partner_nodes_cost_usd[lte]` | No       | number ≥ 0                                                                                                        | N/A                            | Include runs whose Partner Nodes cost is less than or equal to this USD amount. Must be greater than or equal to `partner_nodes_cost_usd[gte]` when both are set.                                                                                                           | `/runs?partner_nodes_cost_usd[lte]=1.00`                                               |
| `expand`                      | No       | Comma-separated list of `prompt`, `workflow`, `outputs`, `outputs.presigned_url`, or `partner_nodes_cost_details` | N/A                            | Expand each run in the response with additional fields. `outputs` and `outputs.presigned_url` are mutually exclusive — include only one per request. When `outputs.presigned_url` is requested, output files are included with a time-limited pre-signed URL for each file. | `/runs?expand=outputs/runs?expand=outputs.presigned_url&presigned_url_expires_in=3600` |
| `presigned_url_expires_in`    | No       | `number`                                                                                                          | `300` seconds<br />(5 minutes) | The presigned\_url expiration time in second between `30` and `84600` (24 hours).<br /><br />Requires `expand` to include `outputs.presigned_url`                                                                                                                           |                                                                                        |
| `sort`                        | No       | `requested_at`, `flotime_ms`, or `partner_nodes_cost_usd`, optionally followed by `.asc` or `.desc`               | `requested_at.desc`            | Sort order for the result set. When a direction is omitted, `asc` is used. <br />When `sort` is omitted entirely, runs are sorted by `requested_at` descending (newest first).                                                                                              | `/runs?sort=flotime_ms.desc`                                                           |
| `limit`                       | No       | integer between `1` and `50`                                                                                      | `25`                           | Maximum number of runs to return in a single page.                                                                                                                                                                                                                          | `/runs?limit=10`                                                                       |
| `cursor`                      | No       | `string` (max 64 characters)                                                                                      | N/A                            | Opaque pagination cursor returned by a previous list-runs response. Use with the same filters, search, sort, and expand values as the request that produced the cursor.                                                                                                     | `/runs?cursor=eyJpZCI6InJ1bl8xMjMifQ`                                                  |



RESPONSE:

| Attribute  | Type               | Description                                                                                                       |
| ---------- | ------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `runs`     | `array`            | Array of run objects matching the query.                                                                          |
| `cursor`   | `string` \| `null` | Pagination cursor to pass as the `cursor` query parameter on the next request. `null` when there is no next page. |
| `has_more` | `boolean`          | Whether additional runs are available beyond the current page.                                                    |



Each object in `runs` includes the following attributes:

| Attribute                    | Type      | Description                                                                                                                                                     |
| ---------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                         | `string`  | Unique ID of the run, e.g. `run_vTGqfqzFotmivzRP`.                                                                                                              |
| `object`                     | `run`     | Returned object type, always `run`.                                                                                                                             |
| `name`                       | `string`  | Name of the run.                                                                                                                                                |
| `status`                     | `string`  | Run status. One of `queued`, `running`, `complete`, `failed`, or `canceled`.                                                                                    |
| `source`                     | `string`  | Where the run was created. One of `app` or `api`.                                                                                                               |
| `run_by`                     | `object`  | User who requested the run. Contains `username` and `email`.                                                                                                    |
| `requested_at`               | `string`  | ISO 8601 timestamp when the run was requested.                                                                                                                  |
| `flotime_ms`                 | `integer` | Amount of FloTime used by the run, in milliseconds.                                                                                                             |
| `partner_nodes_cost_usd`     | `number`  | Total Partner Nodes cost for the run, in USD.                                                                                                                   |
| `outputs`                    | `array`   | Present when `expand=outputs` or `expand=outputs.presigned_url` is set. Array of output files (see [Floyo API - Files](https://docs.floyo.ai/floyo-api-files)). |
| `prompt`                     | `object`  | Present when `expand=prompt` is set. ComfyUI API prompt JSON used for the run.                                                                                  |
| `workflow`                   | `object`  | Present when `expand=workflow` is set. Workflow JSON associated with the run. For `api` runs this attribute value will always be `null`                         |
| `partner_nodes_cost_details` | `array`   | Per-node Partner Nodes cost breakdown. Present when `expand=partner_nodes_cost_details` is set.                                                                 |
| `error`                      | `object`  | Present when the run has `status` of `failed`. Structured error object (see the Error Responses section).                                                       |



**EXAMPLE REQUEST:**

cURL

```curl
curl -X GET "https://api.floyo.ai/runs?status=complete&sort=requested_at.desc&limit=3&expand=outputs" \
     -H "Authorization: Bearer <YOUR_API_KEY>" \
     -H "Accept: application/json"
```

***



**EXAMPLE RESPONSES:**

`STATUS 200`: Runs returned successfully.

```json
{
    "runs": [
        {
            "id": "run_V4GE3M8u9RaT9iM4",
            "object": "run",
            "name": "FLOYO API List runs demo #3",
            "status": "complete",
            "source": "api",
            "run_by": {
                "type": "api_key",
                "username": "apik_g7ueqyfl"
            },
            "requested_at": "2026-07-14T18:50:51.874+00:00",
            "flotime_ms": 1159,
            "partner_nodes_cost_usd": 0,
            "outputs": [
                {
                    "id": "file_22ph7aYx2MWUvas3",
                    "file_name": "ComfyUI_00125_.png",
                    "full_path": "output/ComfyUI_00125_.png",
                    "mime_type": "image/png",
                    "created_at": "2026-07-14T18:52:30.580671+00:00",
                    "size_bytes": 363051
                }
            ]
        },
        {
            "id": "run_AGA4qK1D6z9MMVju",
            "object": "run",
            "name": "FLOYO API List runs demo #2",
            "status": "complete",
            "source": "app",
            "run_by": {
                "type": "user",
                "username": "john.doe",
                "email": "john.doe@floyo.ai"
            },
            "requested_at": "2026-07-14T18:50:41.215+00:00",
            "flotime_ms": 3728,
            "partner_nodes_cost_usd": 0,
            "outputs": [
                {
                    "id": "file_22ph7aYx2MWUvas3",
                    "file_name": "ComfyUI_00125_.png",
                    "full_path": "output/ComfyUI_00125_.png",
                    "mime_type": "image/png",
                    "created_at": "2026-07-14T18:52:30.580671+00:00",
                    "size_bytes": 363051
                }
            ]
        },
        {
            "id": "run_K7biz7j4dNWgoj2x",
            "object": "run",
            "name": "FLOYO API List runs demo #1",
            "status": "complete",
            "source": "api",
            "run_by": {
                "type": "api_key",
                "username": "apik_g7ueqyfl"
            },
            "requested_at": "2026-07-14T18:50:32.492+00:00",
            "flotime_ms": 69348,
            "partner_nodes_cost_usd": 0,
            "outputs": [
                {
                    "id": "file_oc7bHyiiUQKKq6nq",
                    "file_name": "ComfyUI_00124_.png",
                    "full_path": "output/ComfyUI_00124_.png",
                    "mime_type": "image/png",
                    "created_at": "2026-07-14T18:52:25.386146+00:00",
                    "size_bytes": 318100
                }
            ]
        }
    ],
    "cursor": "e957ce20.Ew16q1gw9.run_K7biz7j4dNWgoj2x",
    "has_more": true
}
```

`STATUS 400`: Invalid query parameters.

```json
{
  "error": "Invalid request",
  "message": "One or more request parameters are invalid.",
  "details": {
    "status": "Must be one or more of: complete, failed, canceled, running, queued",
    "limit": "Must be at most 50"
  }
}
```

`STATUS 404`: No runs matched the query.

```json
{
  "error": "No runs found",
  "message": "Your query returned no runs. Try adjusting your filters."
}
```

If the request results in a `4xx` or `5xx` error not shown above, see the Error Responses section.

### Example: Monthly Usage Report by listing runs

You can generatet a Monthly Usage Report by listing runs with `requested_at[gte]` and `requested_at[lte]` parameters. For example, to get all workflows for the month of June 2026 (UTC), run the following

```curl
curl -X GET "https://api.floyo.ai/runs?requested_at[gte]=2026-06-01T00:00:00Z&requested_at[lte]=2026-06-30T23:59:59Z" \
     -H "Authorization: Bearer <YOUR_API_KEY>" \
     -H "Accept: application/json"
```



***



# Retrieve a run

Retrieve a run to get it's current status. Completed workflow runs will include FloTime and Partner (3rd-Party) API Nodes usage information.

To retrieve a `run` make an **authenticated** `GET` request to `/runs/<RUN_ID>`.



**QUERY PARAMETERS:**

| Parameter                  | Required | Value                                                                         | Default                      | Description                                                                                                                                                                                   | Example                                                                    |
| -------------------------- | -------- | ----------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `expand`                   | No       | Comma-separated list of`outputs.presigned_url`or `partner_nodes_cost_details` | N/A                          | Expand a the run response by including, for each output, a time-limited, pre-signed URL to the file, and the partner nodes cost details                                                       | `/runs/<RUN_ID>?expand=outputs.presigned_url,partner_nodes_cost_details`   |
| `presigned_url_expires_in` | No       | `number`<br />                                                                | 300 seconds<br />(5 minutes) | The presigned\_url expiration time in second between `30` and `84600` (24 hours).<br /><br />The Floyo API will return a validation error if  `expand=outpus.presigned_url` is not specified. | `/runs/<RUN_ID>?expand=outputs.presigned_url&presigned_url_expires_in=600` |



**RESPONSE:**

| Attribute                    | Type      | Description                                                                                                                      |
| ---------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `id`                         | `string`  | Unique ID of the run, e.g.: `run_vTGqfqzFotmivzRP`                                                                               |
| `status`                     | `string`  | Run status can be either `queued`, `running`, `canceled`, `failed`, `complete`.                                                  |
| `object`                     | `run`     | Returned object type, always `run`.                                                                                              |
| `name`                       | `string`  | Name of the run.                                                                                                                 |
| `flotime_ms`                 | `integer` | Amount of FloTime used by the run, in milliseconds.                                                                              |
| `partner_nodes_cost_usd`     | `number`  | Total Partner Nodes cost for the run, in USD.                                                                                    |
| `requested_at`               | `string`  | ISO8601 timestamp when the run was requested.                                                                                    |
| `source`                     | `string`  | Where the run was created. One of `app` or `api`.                                                                                |
| `run_by`                     | `object`  | User who requested the run. `run_by.type` can be either `user` or `api_key`. For users it also contains `username` and `email`.  |
| `outputs`                    | `array`   | Array of output files (see [Floyo API - Files](docId:9dvDMPoOxgp3tHr-hXH_v)).                                                    |
| `partner_nodes_cost_details` | `object`  | Per-node Partner Nodes cost breakdown. Included when `expand=partner_nodes_cost_details` is set.                                 |
| `error`                      | `object`  | Present when the run has `status` of `failed`. Structured error object (see the **Error Responses** section).                    |



**EXAMPLE REQUEST:**

:::CodeblockTabs
cURL

```curl
curl -X GET https://api.floyo.ai/runs/<RUN_ID>?expand=outputs.presigned_url \
     -H "Authorization: Bearer <YOUR_API_KEY>" \
     -H "Accept: application/json"
```
:::

****

**EXAMPLE RESPONSE:**

****

`STATUS 200`: Run is processing.

```json
{
    "id": "run_kxvBDQqLGece2xe6",
    "object": "run",
    "name": "Your run name",
    "requested_at": "2026-04-27T18:12:02.155+00:00",
    "status": "running"
}
```



`STATUS 200`: Run finished successfully.

```json
{
    "id": "run_vTGqfqzFotmivzRP",
    "object": "run",
    "name": "Floyo API Demo run",
    "flotime_ms": 6402,
    "partner_nodes_cost_usd": 0,
    "source": "app",
    "run_by": {
      "type": "user",
      "username": "john.doe",
      "email": "john.doe@floyo.ai"
    },
    "requested_at": "2026-04-26T13:55:03.334+00:00",
    "status": "complete",
    "outputs": [
        {           
            "id": "file_NS8KPRtb8LJjatAA",
            "file_name": "ComfyUI_00994_.png",
            "size_bytes": 350983,
            "mime_type": "image/png",
            "created_at": "2026-04-21T13:55:32.431054+00:00",
            "input_path": "(as-input)#outputs/ComfyUI_00994_.png"
        }
    ]
}
```



`STATUS 200`: Run finished successfully with expanded outputs presigned urls.

```json
{
    "id": "run_vTGqfqzFotmivzRP",
    "object": "run",
    "name": "Floyo API Demo run",
    "flotime_ms": 6402,
    "partner_nodes_cost_usd": 0,
    "source": "app",
    "run_by": {
      "type": "user",
      "username": "john.doe",
      "email": "john.doe@floyo.ai"
    },
    "requested_at": "2026-04-26T13:55:03.334+00:00",
    "status": "complete",
    "outputs": [
        {
            "id": "file_NS8KPRtb8LJjatAA",
            "file_name": "ComfyUI_00994_.png",
            "size_bytes": 350983,
            "mime_type": "image/png",
            "created_at": "2026-04-21T13:55:32.431054+00:00",
            "input_path": "(as-input)#outputs/ComfyUI_00994_.png",
            "presigned_url": "https://cdn.floyo.ai/file_NS8KPRtb8LJjatAA?token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6InYxIn0.eyJmaWxlX2lkIjoiZmlsZV9OUzhLUFJ0YjhMSmphdEFBIiwiYWtfaWQiOiJqNXJncmNuNCIsImp0aSI6ImRhMzgzMTQ1LTU3MTUtNDdjYy1iZTc3LWU4ZmQyOTczODU0NyIsImlzcyI6ImZsb3lvLWFwaSIsImF1ZCI6ImZsb3lvLWNkbiIsInN1YiI6ImZpbGVfYWNjZXNzIiwiaWF0IjoxNzc3MzEwOTg4LCJuYmYiOjE3NzczMTA5ODgsImV4cCI6MTc3NzM3MDk4OH0.6IXOOIUlM-TBuvJ5tCY6W_EAWhOVRpViI4-5WsHUiSM"
        }
    ]
}
```

If the request results in a `4xx` or `5xx` error, see the [Error Responses](docId\:W37qHjsl3Ldxxz-dYsZd_) section.

***



# Error Responses

When a workflow run fails, the **Floyo API** returns a structured `error` object alongside the run payload. This object is present in two places:

- `GET /runs/<RUN_ID>` — when the run has finished with `status` of `failed` (including runs that failed due to insufficient credits).
- `POST /runs` — when run creation is rejected immediately because of insufficient credits or workflow validation errors.

Each error message follows this shape:

```json
{
  "type": "insufficient_balance",
  "code": "insufficient_flotime_credits",
  "message": "The workflow could not be executed because your team has insufficient FloTime credits. Contact your team admin to add more.",
  "details": { ... }
}
```

ERROR OBJECT ATTRIBUTES

| Attribute | Type     | Description                                                                                                                           |
| --------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `type`    | `string` | High-level error category. One of `insufficient_balance`, `validation`, `runtime`, or `system`.                                       |
| `code`    | `string` | Specific error code for the given `type`. Use this field for programmatic handling.                                                   |
| `message` | `string` | Human-readable description of what went wrong.                                                                                        |
| `details` | `object` | Optional. Error-specific context (e.g. missing files, node errors, restricted models). Omitted when there is nothing extra to report. |

***

## Error types

The `type` field is the primary signal for how to handle a failure:

| `type`                 | Meaning                                                                                                                                                     | Credits                                                                                                                                               |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insufficient_balance` | The run could not start or complete because your team ran out of credits. The `code` field specifies whether FloTime or Partner Nodes credits are depleted. | No credits are consumed — the run is blocked before execution can begin.                                                                              |
| `validation`           | The workflow  failed during the validation step, before execution actually starts (blocked models, missing files, invalid node configuration, etc.).        | **No credits are consumed or debited.** Validation errors happen prior to GPU execution, so no FloTime or Partner Nodes usage is charged.             |
| `runtime`              | The workflow started executing on GPU but a node raised an exception during processing.                                                                     | **Credits may be consumed.** FloTime (and any Partner Nodes usage up to that point) is charged for the time spent executing until the error occurred. |
| `system`               | An internal or unclassified error occurred. Treat as unexpected; the `message` is a safe, generic description.                                              | Depends on when the failure occurred — if execution had started, partial usage may apply.                                                             |



***

## Error codes reference

### `insufficient_balance`

| `code`                               | Description                                                                   |
| ------------------------------------ | ----------------------------------------------------------------------------- |
| `insufficient_flotime_credits`       | Your team does not have enough FloTime credits to execute the workflow.       |
| `insufficient_partner_nodes_credits` | Your team does not have enough Partner Nodes credits to execute the workflow. |

### `validation`

| `code`                             | Description                                                                         | `details` (when present)                     |
| ---------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------- |
| `model_blocked`                    | The workflow references models that are blocked for your team.                      | `restricted_models`, `node_errors`           |
| `invalid_prompt_files`             | One or more files referenced in the prompt were not found in storage.               | `missing_files`                              |
| `missing_node_type`                | The workflow uses a custom node type that is not available on Floyo.                | Node-specific info from the validation layer |
| `prompt_outputs_failed_validation` | One or more output nodes failed validation (e.g. invalid seed or parameter values). | `node_errors`                                |
| `prompt_no_outputs`                | The workflow has no output nodes defined.                                           | —                                            |
| `invalid_workflow`                 | A general workflow validation error that does not match a more specific code.       | `node_errors` (when available)               |

### `runtime`

| `code`       | Description                                                  | `details` (when present) |
| ------------ | ------------------------------------------------------------ | ------------------------ |
| `node_error` | A node raised an exception while the workflow was executing. | `node_type`              |

### `system`

| `code`           | Description                                          |
| ---------------- | ---------------------------------------------------- |
| `internal_error` | An internal error occurred while processing the run. |
| `system_error`   | An unknown or unhandled error occurred.              |



***

## Example responses for failed runs

The examples below show the `error` object in context. Other run fields (`id`, `name`, `requested_at`, etc.) are included where helpful.

***

`STATUS 200`: Run failed — insufficient FloTime credits.

Returned from `GET /runs/:runId` when the team has no FloTime remaining.

```json
{
  "id": "run_kxvBDQqLGece2xe6",
  "object": "run",
  "name": "Floyo API Demo run",
  "flotime_ms": 0,
  "requested_at": "2026-04-27T18:12:02.155+00:00",
  "status": "failed",
  "error": {
    "type": "insufficient_balance",
    "code": "insufficient_flotime_credits",
    "message": "The workflow could not be executed because your team has insufficient FloTime credits. Contact your team admin to add more."
  }
}
```

***

`STATUS 200`: Run failed — insufficient Partner Nodes credits.

Returned from `GET /runs/:runId` when the workflow uses Partner Nodes and the team has no Partner Nodes credits left.

```json
{
  "id": "run_aB3cD4eF5gH6iJ7k",
  "object": "run",
  "name": "Partner API workflow",
  "flotime_ms": 0,
  "requested_at": "2026-04-28T09:30:15.220+00:00",
  "status": "failed",
  "error": {
    "type": "insufficient_balance",
    "code": "insufficient_partner_nodes_credits",
    "message": "The workflow could not be executed because your team has insufficient Partner Nodes credits. Contact your team admin to add more."
  }
}
```

***

`STATUS 200`: Run failed — blocked models.

Returned from `GET /runs/:runId` when the workflow references models restricted for the team.

```json
{
  "id": "run_mN8oP9qR0sT1uV2w",
  "object": "run",
  "name": "Restricted model test",
  "flotime_ms": 1240,
  "requested_at": "2026-04-26T14:22:10.891+00:00",
  "status": "failed",
  "error": {
    "type": "validation",
    "code": "model_blocked",
    "message": "This workflow uses models that are blocked for your team",
    "details": {
        "node_errors": {
            "39": {
            "errors": [
                {
                "type": "model_restricted",
                "details": {
                    "key": "NanoBananaProUnified_floyo",
                    "kind": "closed_source",
                    "label": "Nano Banana Pro Unified (Floyo Partner Nodes)",
                    "reason": "explicit_blacklist"
                },
                "message": "This workflow uses models that are restricted for your team:\n- Nano Banana Pro Unified (Floyo Partner Nodes): explicitly blocked for this team"
                }
            ],
            "class_type": "NanoBananaProUnified_floyo"
            }
        },
        "restricted_models": [
            {
            "key": "NanoBanana2Unified_floyo",
            "kind": "closed_source",
            "label": "Nano Banana 2 Unified (Floyo Partner Nodes)",
            "reason": "explicit_blacklist"
            }
        ]
        }
}
```

***

`STATUS 200`: Run failed — missing input files.

Returned from `GET /runs/:runId` when files referenced in the workflow prompt cannot be found in storage.

```json
{
  "id": "run_xY7zW6vU5tS4rQ3p",
  "object": "run",
  "name": "Image-to-image run",
  "flotime_ms": 0,
  "requested_at": "2026-04-25T11:05:44.102+00:00",
  "status": "failed",
  "error": {
    "type": "validation",
    "code": "invalid_prompt_files",
    "message": "Some files referenced by the prompt were not found in storage",
    "details": {
      "missing_files": [
        "#inputs/missing-reference.png"
      ]
    }
  }
}
```

***

`STATUS 200`: Run failed — node execution error.

Returned from `GET /runs/:runId` when a node throws an exception during workflow execution.

```json
{
  "id": "run_AdVpsnQkLZKFWp2a",
  "object": "run",
  "name": "BitDanceSampler Test",
  "flotime_ms": 0,
  "requested_at": "2026-06-25T14:04:54.423+00:00",
  "status": "failed",
  "error": {
    "type": "runtime",
    "code": "node_error",
    "message": "AttentionMaskConverter._unmask_unattended expects a float `expanded_mask`, got a BoolTensor.\n",
    "details": {
      "node_type": "BitDanceSampler"
    }
  }
}
```

***

`STATUS 400`: Run creation failed — validation error.

Returned from `POST /runs` when the workflow is rejected before queuing (e.g. missing custom node).

```json
{
  "id": "run_hoJPGfEs9QgFpeve",
  "object": "run",
  "name": "Vae Decode Missing",
  "flotime_ms": 0,
  "requested_at": "2026-06-25T02:05:12.167+00:00",
  "status": "failed",
  "error": {
    "type": "validation",
    "code": "missing_node_type",
    "message": "Node 'VAE Decode' not found. The custom node may not be installed.",
    "details": {
      "node_id": "8",
      "class_type": "VAEDecode",
      "node_title": "VAE Decode"
    }
  }
}
```

***

`STATUS 200`: Run failed — unknown system error.

Returned from `GET /runs/:runId` when the failure cannot be classified into a specific validation or runtime error.

```json
{
  "id": "run_qR4sT5uV6wX7yZ8a",
  "object": "run",
  "name": "API Run - 2026-04-27 18:12:02",
  "flotime_ms": 2100,
  "requested_at": "2026-04-27T18:12:02.155+00:00",
  "status": "failed",
  "error": {
    "type": "system",
    "code": "system_error",
    "message": "Run failed due to an unknown error. We have been notified and are working on a fix"
  }
}
```

