How to Poll Async Image Tasks with the Flux Tasks API

Async image generation needs two separate operations: creating the work and checking the task that was already created. Save the returned platform task ID so a slow response or a page refresh does not turn into an accidental second generation request.

This guide from Ace Data Cloud covers the Flux Tasks API for an existing image-generation task. The same task endpoint also supports platform task IDs returned by Flux video generation. The request and response examples below are illustrative; they are not results from a live call made for this article.

Updated October 18, 2026: restored the missing endpoint names, field names and code examples.

What you can query

Use the task ID returned by the original generation request:

• Base URL: https://api.acedata.cloud
• Endpoint: POST /flux/tasks
• Authentication: authorization: Bearer {token}
• Headers: accept: application/json and content-type: application/json
• Single task action: retrieve, with an id
• Batch action: retrieve_batch, with an ids array

These are retrieval operations even though the endpoint uses HTTP POST. Keep them separate from a generation request. Use an authorized token and an existing task ID; the placeholders in this article will not retrieve a real task.

Retrieve one task

Replace {token} and YOUR_EXISTING_TASK_ID in your own authorized environment. Avoid publishing command output that contains credentials, customer inputs or private result links.

curl --max-time 20 -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "id": "YOUR_EXISTING_TASK_ID",
    "action": "retrieve"
  }'

The following shortened example illustrates a completed task record. In the maintained reference, the original request is in request, and the generation result is nested in response:

{
  "id": "YOUR_EXISTING_TASK_ID",
  "created_at": 1736304669.779,
  "started_at": 1736304669.839,
  "finished_at": 1736304679.439,
  "elapsed": 9.6,
  "request": {
    "action": "generate",
    "size": "1024x1024",
    "prompt": "a white siamese cat"
  },
  "trace_id": "EXAMPLE_TRACE_ID",
  "response": {
    "success": true,
    "task_id": "YOUR_EXISTING_TASK_ID",
    "data": [
      {
        "image_url": "https://cdn.acedata.cloud/e724d7f13d.png"
      }
    ]
  }
}

The reference documents these timing fields:

• created_at: creation time, as a Unix timestamp in seconds.
• started_at: execution start time, as a Unix timestamp in seconds.
• finished_at: completion time; omitted when the task has not completed.
• elapsed: execution duration in seconds; omitted when the task has not completed.

finished_at marks completion, not necessarily a successful usable image. Inspect the nested response and its success or error information. For this successful image example, the output location is response.data[].image_url. An HTTP 200 response from the lookup alone does not establish that generation succeeded.

Keep enough state to resume the lookup

A small application record can retain the platform task id, the relevant internal job reference, the last confirmed state, the query time and trace_id when available. Store task timing and the final response when returned, with access controls appropriate to its contents.

Keep a reference to the original input in an authorized store when it is needed for support. A task record can contain the original prompt and output links; copying its entire body into a public ticket is unnecessary.

Distinguish the task's last observed state from the state of the poller. For example, “last observed pending; lookup timed out” means the latest observation is unavailable. It does not establish that the task failed or was cancelled.

Retrieve a batch of existing tasks

For a dashboard or recovery worker, send multiple task IDs using retrieve_batch:

curl --max-time 20 -X POST 'https://api.acedata.cloud/flux/tasks' \
  -H 'accept: application/json' \
  -H 'authorization: Bearer {token}' \
  -H 'content-type: application/json' \
  -d '{
    "ids": ["YOUR_FIRST_EXISTING_TASK_ID", "YOUR_SECOND_EXISTING_TASK_ID"],
    "action": "retrieve_batch"
  }'

The batch response has an items array and a count. Each returned item follows the task-record structure used for a single lookup. Match items to your saved jobs by id; keep each job's state separate.

A backend worker can consolidate polling so every browser tab does not independently query the same task. Choose a polling interval, per-query timeout, total observation window and maximum query count appropriate to the application. Those are your monitoring limits, not a request to cancel the generation task.

Handle lookup errors separately from generation results

The reference lists these HTTP statuses and error codes:

HTTP status	Error code	Next check
400	token_mismatched	Check required parameters and the request shape
400	api_not_implemented	Check the supported path and action
401	invalid_token	Check the authorized token used for the lookup
429	too_many_requests	Slow down subsequent queries
500	api_error	Retain the diagnostic reference and investigate the query failure

An illustrative error body is:

{
  "success": false,
  "error": {
    "code": "api_error",
    "message": "fetch failed"
  },
  "trace_id": "EXAMPLE_TRACE_ID"
}

Record whether an error came from the lookup request or from the stored generation response. A lookup error by itself does not determine the generation outcome. After a query timeout or rate limit, preserve the existing task ID and use a bounded retrieval policy. Do not automatically resubmit generation just because observation stopped.

A polling workflow to review

1. Persist the task ID returned by the original generation request.
2. Query /flux/tasks using action: "retrieve" and that same id.
3. If the returned record has no finished_at, retain the pending observation and query again within the monitoring limits.
4. When completion is recorded, inspect response for success or failure and retain the relevant result.
5. When a query fails or the observation window ends, record that condition separately and keep the original ID for reconciliation.

For batch processing, use retrieve_batch while keeping the same per-task checks. Consult the maintained Flux Tasks API integration guide for the complete request and response examples.