Floyo API - Workflow Runs

34 min

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:

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.

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

If the request results in a 4xx or 5xx error, see the Error ResponsesResponse Errors section.

Cancel a run

To cancel an active run you must make an authenticated POST request to /runs/<RUN_ID>/cancel.

A run can be canceled only if its current status is either in queuedor running.

EXAMPLE REQUEST:

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.

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

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

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

STATUS 404: Run not found.

{ "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, running, complete, failed orcanceled(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 (5 minutes)	The presigned_url expiration time in second between 30 and 84600 (24 hours). 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. 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).
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 -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.

{
    "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": "[email protected]"
            },
            "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.

{
  "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.

{
  "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 -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 ofoutputs.presigned_urlor 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	300 seconds (5 minutes)	The presigned_url expiration time in second between 30 and 84600 (24 hours). 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 - FilesFiles).
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:

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.

{
    "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.

{
    "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": "[email protected]"
    },
    "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.

{
    "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": "[email protected]"
    },
    "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"
        }
    ]
}

{ "id": "run_vTGqfqzFotmivzRP", "object": "run", "name": "Floyo API Demo run", "flotime_ms": 6402, "requested_at": "2026-04-26T13:55:03.334+00:00", "status": "done", "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", "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 ResponsesResponse Errors 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:

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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.

{
  "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).

{
  "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.

{
  "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"
  }
}