Floyo API - Workflow Runs

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 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 responses docid\ w37qhjsl3ldxxz dyszd section cancel a run to cancel an active run you must make an authenticated post request to /runs/\ runid/cancel a run can be cancelled only if its current status is either in queued or processing example request 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 cancelled { "id" "run c7d3esgnvhj1a6ts", "object" "run", "message" "run cancelled" } status 409 run was cancelled, has finished or failed { "id" "run c7d3esgnvhj1a6ts", "status" "cancelled", "object" "run", "error" "run is already finished", "message" "run was cancelled by the user" } status 404 run not found { "error" "run not found" } 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/\ runid query parameters parameter required value default description example expand no outputs presigned url n/a expand a the run response by including, for each output, a time limited, pre signed url to the file /files/\<file id>?expand=outputs presigned url presigned url expires in no number 300 seconds (5 minutes) the presigned url expiration time in second between 30 and 604800 (1 week) the floyo api will return a validation error if expand=outpus presigned url is not specified /files/\<file 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 , processing , cancelled , failed , done 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 requested at string iso8601 timestamp when the run was requested outputs array array of output files (see floyo api files docid 9dvdmpooxgp3thr hxh v ) example request 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 { "id" "run kxvbdqqlgece2xe6", "object" "run", "name" "your run name", "requested at" "2026 04 27t18 12 02 155+00 00", "status" "processing" } status 200 run finished successfully { "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", "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, "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", "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/\ runid — 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" } }