# Batches
Source: https://www.meilisearch.com/docs/reference/api/batches

The /batches route allows you to monitor how Meilisearch is grouping and processing asynchronous operations.

The `/batches` route gives information about the progress of batches of [asynchronous operations](/learn/async/asynchronous_operations).

## Batch object

```json theme={null}
{
  "uid": 0,
  "progress": {
    "steps": [
      { 
        "currentStep": "extracting words",
        "finished": 2,
        "total": 9,
      },
      {
        "currentStep": "document",
        "finished": 30546,
        "total": 31944,
      }
    ],
    "percentage": 32.8471
  },
  "details": {
    "receivedDocuments": 6,
    "indexedDocuments": 6
  },
  "stats": {
    "totalNbTasks": 1,
    "status": {
      "succeeded": 1
    },
    "types": {
      "documentAdditionOrUpdate": 1
    },
    "indexUids": {
      "INDEX_NAME": 1
    }, 
    "progressTrace": { … },
    "writeChannelCongestion": { … },
    "internalDatabaseSizes": { … },
    "embedderRequests": {
      "total": 12,
      "failed": 5,
      "lastError": "runtime error: received internal error HTTP 500 from embedding server\n  - server replied with `{\"error\":\"Service Unavailable\"}`"
    }
  },
  "duration": "PT0.250518S",
  "startedAt": "2024-12-10T15:20:30.18182Z",
  "finishedAt": "2024-12-10T15:20:30.432338Z",
  "batchStrategy": "batched all enqueued tasks"
}
```

### `uid`

**Type**: Integer<br />
**Description**: Unique sequential identifier of the batch. Starts at `0` and increases by one for every new batch.

### `details`

**Type**: Object<br />
**Description**: Basic information on the types tasks in a batch. Consult the [task object reference](/reference/api/tasks#details) for an exhaustive list of possible values.

### `progress`

**Type**: Object<br />
**Description**: Object containing two fields: `steps` and `percentage`. Once Meilisearch has fully processed a batch, its `progress` is set to `null`.

#### `steps`

Information about the current operations Meilisearch is performing in this batch. A step may consist of multiple substeps.

| Name              | Description                                        |
| :---------------- | :------------------------------------------------- |
| **`currentStep`** | A string describing the operation                  |
| **`total`**       | The total number of operations in the step         |
| **`finished`**    | The number of operations Meilisearch has completed |

<Tip>
  If Meilisearch is taking longer than expected to process a batch, monitor the `steps` array. If the `finished` field of the last item in the `steps` array does not update, Meilisearch may be stuck.
</Tip>

#### `percentage`

The percentage of completed operations, calculated from all current steps and substeps. This value is a rough estimate and may not always reflect the current state of the batch due to how different steps are processed more quickly than others.

### `stats`

**Type**: Object<br />
**Description**: Detailed information on the payload of all tasks in a batch.

#### `totalNbTasks`

Number of tasks in the batch.

#### `status`

Object listing the [status of each task](/reference/api/tasks#status) in the batch. Contains five keys whose values correspond to the number of tasks with that status.

#### `types`

List with the `types` of tasks contained in the batch.

#### `indexUids`

List of the number of tasks in the batch separated by the indexes they affect.

#### `progressTrace`

List with full paths for each operation performed in the batch, together with the processing time in human-readable format.

#### `writeChannelCongestion`

Object containing information on write operations computed during indexing. Can be useful when diagnosing performance issues associated with write speeds.

#### `internalDatabaseSizes`

Size of each internal database, including by how much it changed after a batch was processed.

#### `embedderRequests`

Object containing the total number of requests made to the embedder. Also displays the number of failed requests, if any, along with the error message for the most recent failure.

Only present in batches with at least one task querying an embedder. This field continuously updates until Meilisearch finishes processing the batch.

### `duration`

**Type**: String<br />
**Description**: The total elapsed time the batch spent in the `processing` state, in [ISO 8601](https://www.ionos.com/digitalguide/websites/web-development/iso-8601/) format. Set to `null` while the batch is processing tasks

### `startedAt`

**Type**: String<br />
**Description**: The date and time when the batch began `processing`, in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format

### `finishedAt`

**Type**: String<br />
**Description**: The date and time when the tasks finished `processing`, whether `failed`, `succeeded`, or `canceled`, in [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format

### `batchStrategy`

**Type**: String<br />
**Description**: A string describing the logic behind the creation of the batch. Can contain useful information when diagnosing indexing performance issues.

## Get batches

<RouteHighlighter method="GET" />

List all batches, regardless of index. The batch objects are contained in the `results` array.

Batches are always returned in descending order of `uid`. This means that by default, **the most recently created batch objects appear first**.

Batch results are [paginated](/learn/async/paginating_tasks) and can be [filtered](/learn/async/filtering_tasks) with query parameters.

<Warning>
  Some query parameters for `/batches`, such as `uids` and `statuses`, target tasks instead of batches.

  For example, `?uids=0` returns a batch containing the task with a `taskUid` equal to `0`, instead of a batch with a `batchUid` equal to `0`.
</Warning>

### Query parameters

| Query Parameter        | Default Value                   | Description                                                                                                       |
| ---------------------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **`uids`**             | `*` (all task uids)             | Select batches containing the tasks with the specified `uid`s. Separate multiple task `uids` with a comma (`,`)   |
| **`batchUids`**        | `*` (all batch uids)            | Filter batches by their `uid`. Separate multiple batch `uids` with a comma (`,`)                                  |
| **`indexUids`**        | `*` (all indexes)               | Select batches containing tasks affecting the specified indexes. Separate multiple `indexUids` with a comma (`,`) |
| **`statuses`**         | `*` (all statuses)              | Select batches containing tasks with the specified `status`. Separate multiple task `statuses` with a comma (`,`) |
| **`types`**            | `*` (all types)                 | Select batches containing tasks with the specified `type`. Separate multiple task `types` with a comma (`,`)      |
| **`limit`**            | `20`                            | Number of batches to return                                                                                       |
| **`from`**             | `uid` of the last created batch | `uid` of the first batch returned                                                                                 |
| **`reverse`**          | `false`                         | If `true`, returns results in the reverse order, from oldest to most recent                                       |
| **`beforeEnqueuedAt`** | `*` (all tasks)                 | Select batches containing tasks with the specified `enqueuedAt` field                                             |
| **`beforeStartedAt`**  | `*` (all tasks)                 | Select batches containing tasks with the specified `startedAt` field                                              |
| **`beforeFinishedAt`** | `*` (all tasks)                 | Select batches containing tasks with the specified `finishedAt` field                                             |
| **`afterEnqueuedAt`**  | `*` (all tasks)                 | Select batches containing tasks with the specified `enqueuedAt` field                                             |
| **`afterStartedAt`**   | `*` (all tasks)                 | Select batches containing tasks with the specified `startedAt` field                                              |
| **`afterFinishedAt`**  | `*` (all tasks)                 | Select batches containing tasks with the specified `finishedAt` field                                             |

### Response

| Name          | Type    | Description                                                                                                                    |
| :------------ | :------ | :----------------------------------------------------------------------------------------------------------------------------- |
| **`results`** | Array   | An array of [batch objects](#batch-object)                                                                                     |
| **`total`**   | Integer | Total number of batches matching the filter or query                                                                           |
| **`limit`**   | Integer | Number of batches returned                                                                                                     |
| **`from`**    | Integer | `uid` of the first batch returned                                                                                              |
| **`next`**    | Integer | Value passed to `from` to view the next "page" of results. When the value of `next` is `null`, there are no more tasks to view |

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X GET 'http://MEILISEARCH_URL/batches'
  ```

  ```javascript JS theme={null}
  client.batches.getBatches();
  ```

  ```python Python theme={null}
  client.get_batches()
  ```

  ```php PHP theme={null}
  $client->getBatches();
  ```

  ```ruby Ruby theme={null}
  client.batches
  ```

  ```go Go theme={null}
  client.GetBatches();
  ```

  ```rust Rust theme={null}
  let mut query = meilisearch_sdk::batches::BatchesQuery::new(&client);
  query.with_limit(20);
  let batches: meilisearch_sdk::batches::BatchesResults =
    client.get_batches_with(&query).await.unwrap();
  ```
</CodeGroup>

#### Response: `200 Ok`

```json theme={null}
{
  "results": [
    {
      "uid": 2,
      "progress": null,
      "details": {
        "stopWords": [
          "of",
          "the"
        ]
      },
      "stats": {
        "totalNbTasks": 1,
        "status": {
          "succeeded": 1
        },
        "types": {
          "settingsUpdate": 1
        },
        "indexUids": {
          "INDEX_NAME": 1
        },
        "progressTrace": { … },
        "writeChannelCongestion": { … },
        "internalDatabaseSizes": { … },
        "embedderRequests": {
          "total": 12,
          "failed": 5,
          "lastError": "runtime error: received internal error HTTP 500 from embedding server\n  - server replied with `{\"error\":\"Service Unavailable\"}`"
        }
      },
      "duration": "PT0.110083S",
      "startedAt": "2024-12-10T15:49:04.995321Z",
      "finishedAt": "2024-12-10T15:49:05.105404Z",
      "batchStrategy": "batched all enqueued tasks"
    }
  ],
  "total": 3,
  "limit": 1,
  "from": 2,
  "next": 1
}
```

## Get one batch

<RouteHighlighter method="GET" />

Get a single batch.

### Path parameters

| Name               | Type   | Description                          |
| :----------------- | :----- | :----------------------------------- |
| **`batch_uid`** \* | String | [`uid`](#uid) of the requested batch |

### Example

<CodeGroup>
  ```bash cURL theme={null}
  curl \
    -X GET 'http://MEILISEARCH_URL/batches/BATCH_UID'
  ```

  ```javascript JS theme={null}
  client.batches.getBatch(BATCH_UID);
  ```

  ```python Python theme={null}
  client.get_batch(BATCH_UID)
  ```

  ```php PHP theme={null}
  $client->getBatch(BATCH_UID);
  ```

  ```ruby Ruby theme={null}
  client.batch(BATCH_UID)
  ```

  ```go Go theme={null}
  client.GetBatch(BATCH_UID);
  ```

  ```rust Rust theme={null}
  let uid: u32 = 42;
  let batch: meilisearch_sdk::batches::Batch = client
    .get_batch(uid)
    .await
    .unwrap();
  ```
</CodeGroup>

#### Response: `200 Ok`

```json theme={null}
{
  "uid": 1,
  "details": {
    "receivedDocuments": 1,
    "indexedDocuments": 1
  },
  "progress": null,
  "stats": {
    "totalNbTasks": 1,
    "status": {
      "succeeded": 1
    },
    "types": {
      "documentAdditionOrUpdate": 1
    },
    "indexUids": {
      "INDEX_NAME": 1
    },
    "progressTrace": { … },
    "writeChannelCongestion": { … },
    "internalDatabaseSizes": { … },
    "embedderRequests": {
      "total": 12,
      "failed": 5,
      "lastError": "runtime error: received internal error HTTP 500 from embedding server\n  - server replied with `{\"error\":\"Service Unavailable\"}`"
    }
  },
  "duration": "PT0.364788S",
  "startedAt": "2024-12-10T15:48:49.672141Z",
  "finishedAt": "2024-12-10T15:48:50.036929Z",
  "batchStrategy": "batched all enqueued tasks"
}
```