> For the complete documentation index, see [llms.txt](https://docs.flora.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.flora.ai/mcp/runs.md).

# FLORA MCP runs: polling, timeouts and failures

Follow FLORA MCP runs from start to finish: run statuses, polling a batch with flora\_list\_generations, Technique runs, how long runs take, stuck runs, and what to do with each error code.

Every generation or Technique your agent starts through [FLORA MCP](https://flora.ai/mcp) is a run: it gets a `run_id` right away and finishes in the background. This page covers how to wait for runs without hitting rate limits, how long they take, when to call one stuck, and what each failure code means.

## The run lifecycle

`flora_create_generations`, `flora_run_technique`, `flora_run_canvas_nodes` and `flora_train_lora` return a `run_id` as soon as the run is accepted. A started generation also returns its `node_id`, the `canvas_url` to give the user, a `charged_cost` estimate and `estimated_seconds`. The node is on the canvas from the start and fills in when the run finishes.

A run read reports one of four statuses:

| `status`    | Meaning                                                                                                                                                      | What to do                                     |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| `pending`   | Accepted and waiting to start (queued for a slot or for the model)                                                                                           | Keep polling at the poll interval              |
| `running`   | The model is working                                                                                                                                         | Keep polling at the poll interval              |
| `completed` | Finished. `outputs` holds the results and `charged_cost` the cost                                                                                            | Show the outputs, or use them in the next step |
| `failed`    | Finished without a result. `error_code` and `error_message` say why. A `failed` run with no `error_code` was most likely cancelled by a person in the canvas | Act on the [error class](#error-codes)         |

`completed` and `failed` are final. A run never changes after that, and a failed run doesn't retry on its own.

Key on `status` only. For generation runs, `progress` reads `0` until the run ends and `100` after, for failures too, so it's not a progress bar. Technique runs fill in `progress` as their steps finish.

## Poll a batch

{% hint style="info" %}
**Polling rule.** Save every `run_id`. Wait at least 15 seconds between polls, or 2 seconds per run for bigger batches (40 seconds for 20 runs). Then read every `run_id` in one `flora_list_generations` call (up to 20 per call). For example: `flora_list_generations({"run_ids": ["run_a", "run_b"]})`. For Technique runs, also pass `"technique_id"`. Polling faster returns `429` or cooldown errors with `retry_after_seconds`.
{% endhint %}

Read every run of a batch in one call. `run_ids` is an array even for one run:

```json
{
  "run_ids": ["run_a1", "run_b2", "run_c3"]
}
```

The response has one entry per ID, in the order you sent them:

```json
{
  "runs": [
    {
      "run_id": "run_a1",
      "status": "completed",
      "progress": 100,
      "created_at": 1760195045000,
      "started_at": 1760195046000,
      "completed_at": 1760195112000,
      "charged_cost": 0.072,
      "outputs": [
        {
          "output_id": "output_1",
          "type": "imageUrl",
          "url": "https://media.flora.ai/…",
          "asset_id": "asset_abc"
        }
      ]
    },
    {
      "run_id": "run_b2",
      "status": "failed",
      "progress": 100,
      "created_at": 1760195045000,
      "error_code": "GENERATION_PROMPT_MODERATED",
      "error_message": "Your input was flagged by safety filters."
    },
    {
      "run_id": "run_c3",
      "status": "running",
      "progress": 0,
      "created_at": 1760195045000
    }
  ]
}
```

Output `type` is one of `imageUrl`, `videoUrl`, `audioUrl`, `text`, `documentUrl` or `model3dUrl`. Pass an output's `asset_id` or `url` to the next step. For 3D results, `flora_view_model3d` with the `run_id` opens a viewer.

### Why the poll rule exists

Every ID in `run_ids` is one API request against the per-minute rate limit, which is counted against your credential's [default workspace](https://docs.flora.ai/mcp/cost-and-limits.md#default-workspace) and shared with every agent, API key and script counted there. Polling a 20-run batch every few seconds would use the whole budget on status checks and starve the work itself. So the MCP server enforces the interval:

* After a successful read, the same runs can't be read again for `max(15, 2 × number of run_ids)` seconds. Reading early returns a cooldown entry with `status: 429` and `retry_after_seconds`, never cached data.
* If the API itself rate-limits a read, that run cools down for 60 seconds.
* If every ID in a call is cooling down, the whole call fails with `retry_after_seconds`. Wait that long.

| Runs in the batch | Wait between polls |
| ----------------- | ------------------ |
| 1 to 7            | 15 seconds         |
| 10                | 20 seconds         |
| 15                | 30 seconds         |
| 20                | 40 seconds         |

Make the first poll after the same interval, `max(15 s, 2 s × runs)`: runs can finish earlier than their estimate. For slow models, such as video, it's fine to wait longer (about `estimated_seconds`) before the first poll to save requests. Agents that can't sleep between calls can tell the user the work is running and check back on the next turn.

### Entries that aren't runs

An ID that isn't a run gets its own `ok: false` entry, and the rest of the batch still reads:

```json
{
  "run_id": "n7",
  "ok": false,
  "error": "n7 is not a run id: run ids start with run_, have a nonempty suffix without whitespace, and are returned as run_id by flora_create_generations and flora_run_technique. Canvas node ids, asset ids and history entries cannot be read here."
}
```

Canvas node IDs, asset IDs and quote entries have no run to read. Only pass the `run_id` values that `flora_create_generations`, `flora_run_technique`, `flora_run_canvas_nodes` or `flora_train_lora` returned.

### History instead of exact runs

Leave out `run_ids` to list history, newest first, with optional `workspace_id`, `project_id`, `status`, `limit` and `cursor` filters. Add `include_inputs: true` to get each run's submitted prompt and references. Use history to find runs you lost track of, never as a substitute for reading the IDs you hold.

## Technique runs

`flora_run_technique` returns a `run_id` too. Poll it with the same tool and pass the Technique's ID:

```json
{
  "run_ids": ["run_t1", "run_t2"],
  "technique_id": "tech_abc"
}
```

`technique_id` applies to every ID in the call, so read Technique runs and plain generation runs in separate calls. A Technique run bills your credential's [default workspace](https://docs.flora.ai/mcp/cost-and-limits.md#default-workspace), because `flora_run_technique` takes no `workspace_id`. To list past Technique runs, use `flora_list_technique_runs`.

## How long runs take

Each model reports `estimated_seconds` in `flora_list_models`, and a started generation returns it too. In the catalog today:

| Output    | Typical `estimated_seconds`                                                                                  |
| --------- | ------------------------------------------------------------------------------------------------------------ |
| Image     | Most models 20 to 90 seconds. The fastest take about 5 seconds; a few vector models estimate about 8 minutes |
| Video     | Most models 2 to 5 minutes. The slowest take up to about 26 minutes                                          |
| Audio     | 5 to 40 seconds                                                                                              |
| 3D        | About 5 minutes                                                                                              |
| Technique | No estimate. See [Technique timing](#technique-timing)                                                       |

These are estimates, not promises: read `estimated_seconds` for the model you picked, and expect longer at busy times when the model's queue is long. Runs in one `flora_create_generations` call start together, so a batch of 20 takes about as long as its slowest item, not 20 times as long.

### Technique timing

Techniques don't report `estimated_seconds`. A Technique runs its steps as model generations, so it takes at least as long as its slowest step, and longer when steps run one after another.

* Wait 15 seconds, the minimum poll interval, before the first poll. Then poll at the interval.
* For a real estimate, read a recent run of the same Technique with `flora_list_technique_runs` (pass `technique_id` and `status: "completed"`) and compare its `started_at` and `completed_at`.
* Technique runs fill in `progress` as their steps finish, so a rising `progress` means the run is moving.
* FLORA fails a Technique run that hasn't finished after 60 minutes, with `TECHNIQUE_TIMEOUT`.

## When a run seems stuck

Don't judge a run by elapsed time alone. FLORA ends runs that overrun on its own:

* A generation that runs far past its estimate fails with `GENERATION_PROVIDER_TIMEOUT`. The deadline is set when the model provider accepts the job: the larger of 7 minutes and 8 × `estimated_seconds`, plus half of `estimated_seconds` for every job ahead of it in the provider's queue at that moment. There's no fixed overall cap, so a long provider queue pushes the deadline out.
* A Technique run fails with `TECHNIQUE_TIMEOUT` after 60 minutes.
* A run waiting for an account slot (new accounts run one generation at a time) fails with `GENERATION_QUEUE_NOT_MOVING` after an hour.

A failed run isn't charged, so a run that times out costs nothing.

**Stop waiting** when a generation is still `pending` or `running` after 8 × `estimated_seconds` (at least 7 minutes), or when a Technique run takes well past what earlier runs of the same Technique took. Then:

1. Tell the user it's taking longer than expected, and give them the `run_id` and the `canvas_url`. The node fills in on the canvas as soon as the result lands.
2. Don't start the same request again. The original may still finish and bill, and a second copy bills again.
3. Check the run again later, or in the next conversation, with `flora_list_generations`. FLORA either finishes it or fails it on its own.
4. If a later check still shows it `pending` or `running`, email <support@florafauna.ai> with the `run_id`, the time you started it, your client and the tool you called.

### Cancelling

There's no cancel tool and no cancel endpoint in the API. A person can stop a run from the canvas: open the `canvas_url`, right-click the running node and choose **Cancel generation** (see [How Nodes Run](https://docs.flora.ai/nodes/how-nodes-run.md#cancelling)). That stops a run that hasn't reached the model yet. A run the model provider already accepted keeps going and is still billed; cancelling only keeps its result off the node.

## After a timeout, check before you retry

If a create call times out or the conversation drops, the run may have started anyway. `flora_create_generations` has no idempotency key, so firing again can bill twice. Read history first:

```json
{
  "project_id": "prj_abc",
  "include_inputs": true,
  "limit": 20
}
```

Match the submitted prompts against what you meant to start, and re-fire only what's missing. For Techniques, check `flora_list_technique_runs` with the `technique_id`. Two tools do protect against duplicates: reuse the same `idempotency_key` when you retry `flora_add_to_canvas`, and the same `client_token` when you retry `flora_train_lora`.

## Error codes

Failures show up in two places:

* **At start:** a `flora_create_generations` entry with `ok: false`, an `error` and an HTTP `status`. Nothing started and nothing was charged for that entry.
* **On a run:** a run read with `status: "failed"`, an `error_code` and an `error_message`. The run's cost was released.

Classify by code, then **read `error_message` before acting**. `GPU_PROVIDER_ERROR` and `GENERATION_NO_RESULT` often carry a model's safety refusal ("rejected by the safety system", "declined this request"). If the message names safety, moderation, a refusal or a policy, treat it as **change the input**, whatever the code. Retrying a refusal unchanged fails the same way.

### Retry now

Transient. Retry once, as a new run; if it fails the same way again, report it.

| Code                                                                                                         | Meaning                                                                                                 |
| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `GENERATION_PROVIDER_TIMEOUT`                                                                                | The model took too long                                                                                 |
| `GENERATION_FAILED_TO_START`, `GENERATION_PROVIDER_FAILED_TO_START`                                          | The run couldn't start                                                                                  |
| `GENERATION_GENERIC_ERROR`, `GPU_PROVIDER_ERROR`, `SERVER_ERROR`                                             | Unexpected error during the run (check the message for a refusal)                                       |
| `GENERATION_PREGENERATION_FAILED`, `GENERATION_POSTGENERATION_FAILED`, `GENERATION_MAP_AFTER_REQUEST_FAILED` | Preparing the input or processing the result failed                                                     |
| `GENERATION_FAILED_TO_UPLOAD`, `GENERATION_FAILED_TO_UPDATE`, `GENERATION_FAILED_TO_GET`                     | FLORA couldn't save or read the result                                                                  |
| `TECHNIQUE_GENERATION_FAILED`                                                                                | A step inside a Technique failed                                                                        |
| HTTP `500` `internal_error` or `unknown_error`                                                               | The API failed. Check that the `prj_` and `ws_` IDs are real first: a malformed ID can surface as a 500 |

### Retry later

The model or provider is overloaded or down. Wait a few minutes before one retry, or switch to another model.

| Code                                                                      | Meaning                                                                                                                                                                                                                        |
| ------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `GENERATION_QUEUE_TOO_LARGE`                                              | The model is at capacity                                                                                                                                                                                                       |
| `GENERATION_QUEUE_NOT_MOVING`                                             | The run waited too long to start                                                                                                                                                                                               |
| `GENERATION_DOWNSTREAM_SERVICE_ERROR`, `GENERATION_CIRCUIT_BREAKER_OPEN`  | The model provider is having problems                                                                                                                                                                                          |
| `GENERATION_INVALID_PROVIDER_RESPONSE`, `GENERATION_NO_RESULT`            | The model returned nothing usable (check the message for a refusal)                                                                                                                                                            |
| `GENERATION_MODAL_POLL_ERROR`, `GENERATION_PROVIDER_FAILED_TO_GET_STATUS` | FLORA lost track of the provider's job                                                                                                                                                                                         |
| `AUDIO_GENERATION_ERROR`                                                  | Audio generation failed at the provider                                                                                                                                                                                        |
| HTTP `429` `rate_limited`, or a cooldown entry                            | Too many requests. Wait `retry_after_seconds` when it's there. The API's own 429 ("Rate limit exceeded.") has no wait value, so back off about 60 seconds. Then retry reads; don't blindly retry a create, check history first |
| HTTP `503` `temporarily_unavailable`                                      | The API is briefly unavailable                                                                                                                                                                                                 |

### Change the input

Retrying the same request fails the same way. Fix the prompt, parameters, model or input first.

| Code                                                                         | Meaning                                                                                                |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `GENERATION_PROMPT_MODERATED`, `LLM_REFUSAL`                                 | A safety filter or the model refused the prompt or input. Rephrase or change the input                 |
| `GENERATION_INPUT_VALIDATION`, `GENERATION_INVALID_PARAMS`                   | An input or setting doesn't fit this model. Read its `params` with `flora_list_models` and `model_id`  |
| `GENERATION_INVALID_URL`                                                     | An input URL is invalid or unreachable. Upload the file with `flora_create_asset`                      |
| `GENERATION_MAP_BEFORE_REQUEST_FAILED`                                       | FLORA couldn't prepare the input for this model                                                        |
| `GENERATION_ENDPOINT_NOT_FOUND`, `GENERATION_PROVIDER_NOT_SUPPORTED`         | The model ID isn't available. Pick one from `flora_list_models`                                        |
| `TEAMS_WORKSPACE_MODEL_NOT_AVAILABLE`, `ACCESS_SERVING_PROVIDER_NOT_ALLOWED` | The workspace or organization doesn't allow this model. Pick another                                   |
| `LLM_OUTPUT_TRUNCATED`                                                       | The text model ran out of room. Ask for less                                                           |
| `LLM_CANNOT_GENERATE_MEDIA`                                                  | A text model was asked for an image or video. Use an image or video model                              |
| `LLM_ERROR`                                                                  | The text model returned an error or no usable answer. Rephrase the request, or pick another text model |
| `TECHNIQUE_NO_OUTPUTS_PRODUCED`                                              | No branch of the Technique matched these inputs                                                        |
| HTTP `400` `input_validation_error`                                          | The request is malformed. The message (and `fields`) names what to fix                                 |
| HTTP `404` `not_found`                                                       | An ID is wrong or belongs to another workspace. Look it up with the matching list tool                 |

### Report it

Not retryable. Stop and tell the user what happened, quoting the message.

| Code                                                                            | Meaning                                                                                                                                                                       |
| ------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `insufficient_credits` (HTTP 402), `BILLING_*`, `GENERATION_NOT_PAID`           | Balance or a spending limit. See [When the money runs out](https://docs.flora.ai/mcp/cost-and-limits.md#when-the-money-runs-out). Relay the message and its link; don't retry |
| `ACCESS_*`, HTTP `403` `forbidden`                                              | The user's role or the credential doesn't allow this in this workspace                                                                                                        |
| `*_ENTITLEMENT_REQUIRED`, HTTP `403` `paid_plan_required`                       | The workspace's plan doesn't include what was asked, such as API access or a feature. Adding balance doesn't fix it. Pick a workspace whose plan includes it, or upgrade      |
| HTTP `401` `unauthorized` or `invalid_api_key`                                  | Sign-in failed. Reconnect the client (see [Troubleshooting](https://docs.flora.ai/mcp/troubleshooting.md#connecting-and-sign-in))                                             |
| `failed` with no `error_code`, or `GENERATION_CANCELLED`                        | Most likely a person cancelled the run in the canvas (a canvas cancel sets no error code). Don't re-run it unless the user asks                                               |
| `TECHNIQUE_NODE_CONFIG_ERROR`, `TECHNIQUE_GRAPH_STUCK`, `TECHNIQUE_GRAPH_CYCLE` | The Technique itself is broken. Tell its owner                                                                                                                                |
| `TECHNIQUE_TIMEOUT`                                                             | The Technique ran for 60 minutes without finishing                                                                                                                            |
| A **retry now** code that failed twice                                          | Send the `run_id` to support                                                                                                                                                  |

## Related

* [Cost, balance and limits](https://docs.flora.ai/mcp/cost-and-limits.md)
* [Troubleshooting](https://docs.flora.ai/mcp/troubleshooting.md)
* [Batch-generate 20 to 500 assets](https://docs.flora.ai/mcp/recipes/batch.md)
* [Run your team's Technique](https://docs.flora.ai/mcp/recipes/run-a-technique.md)
* [Generation and run tools](https://docs.flora.ai/mcp/tools/generations.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.flora.ai/mcp/runs.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
