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

# Batch Queue

Batch Queue exposes asynchronous or grouped operations that cannot be understood from a single item alone. Use it to separate request acceptance from actual processing completion.

### Before you make the change

* Record the operation, expected item count, owner, and correlation or batch ID.
* Know whether retry is safe and idempotent.
* Define the failure destination and reconciliation method.

### Understand the product behavior

Each Batch Queue row represents one upload/import action and shows:

* cover thumbnail or type fallback;
* name and import date;
* data-type chips;
* item count;
* progress bar;
* queue status;
* assignee avatars aggregated from the imported items;
* running automation summary where applicable.

Search matches queue name and metadata. Filters include queue status, assignee, and one or more data types; selecting several types uses OR behavior. Opening a row shows the project data grid scoped to that upload session. Uploading again from inside this detail view reuses the same Batch Queue; uploading from the top-level project page creates a new queue.

The SDK exposes total, completed, processing, and failed counts plus item-level data. A queue can be finished processing and still contain failures, so operators should inspect both the overall state and individual rows.

### Monitor and reconcile a batch

{% stepper %}
{% step %}

#### 1. Open the batch

Identify the originating operation, project, source, owner, and expected population.
{% endstep %}

{% step %}

#### 2. Read status and counts

Separate queued, running, succeeded, failed, cancelled, or other current states.
{% endstep %}

{% step %}

#### 3. Inspect failures

Review representative errors and determine whether the cause is source data, validation, permission, integration, or platform processing.
{% endstep %}

{% step %}

#### 4. Check remote state before retry

Confirm which items already succeeded so a retry does not duplicate work.
{% endstep %}

{% step %}

#### 5. Recover the cohort

Correct the cause, retry only the safe scope, or route failures to an owned exception path.
{% endstep %}

{% step %}

#### 6. Close the record

Reconcile expected and final counts and retain the batch ID and outcome.
{% endstep %}
{% endstepper %}

### Decisions that affect production

| Decision        | Production guidance                                                       |
| --------------- | ------------------------------------------------------------------------- |
| Retry           | Use only after inspecting completed and partial state.                    |
| Partial success | Preserve successful work and isolate the failed cohort.                   |
| Timeout         | A client timeout does not prove the remote operation failed.              |
| Ownership       | Every non-terminal batch needs a named operator and escalation threshold. |

### Continue the operating flow

* Return successful items to their Task Queue stage.
* Inspect repeated failures as a systemic source or integration issue.
* Include important batch IDs in the operational record.