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/\<run id>/cancel a run can be canceled only if its current status is either in queued or running 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 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 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 (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 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 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" "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 { "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 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 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 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 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" "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" "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 { "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 { "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" } }