Working with tasks

In this tutorial, you’ll use the Meilisearch API to add documents to an index, and then monitor its status.

Many Meilisearch operations are processed asynchronously in a task. Asynchronous tasks allow you to make resource-intensive changes to your Meilisearch project without any downtime for users.

In this tutorial, you’ll use the Meilisearch API to add documents to an index, and then monitor its status.

Adding a task to the task queue

Operations that require indexing, such as adding and updating documents or changing an index’s settings, will always generate a task.

Start by creating an index, then add a large number of documents to this index:

cURL

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/documents'\
  -H 'Content-Type: application/json' \
  --data-binary @movies.json

Instead of processing your request immediately, Meilisearch will add it to a queue and return a summarized task object:

{
  "taskUid": 0,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentAdditionOrUpdate",
  "enqueuedAt": "2021-08-11T09:25:53.000000Z"
}

The summarized task object is confirmation your request has been accepted. It also gives you information you can use to monitor the status of your request, such as the taskUid.

You can add documents to a new Meilisearch Cloud index using the Cloud interface. To get the taskUid of this task, visit the “Task” overview and look for a “Document addition or update” task associated with your newly created index.

Monitoring task status

Meilisearch processes tasks in the order they were added to the queue. You can check the status of a task using the Meilisearch Cloud interface or the Meilisearch API.

Monitoring task status in the Meilisearch Cloud interface

Log into your Meilisearch Cloud account and navigate to your project. Click the “Tasks” link in the project menu:

This will lead you to the task overview, which shows a list of all batches enqueued, processing, and completed in your project:

All Meilisearch tasks are processed in batches. When the batch containing your task changes its status to succeeded, Meilisearch has finished processing your request.

If the status changes to failed, Meilisearch was not able to fulfill your request. Check the object’s error field for more information.

Monitoring task status with the Meilisearch API

Use the taskUid from your request’s response to check the status of a task:

cURL

curl \
  -X GET 'MEILISEARCH_URL/tasks/1'

This will return the full task object:

{
  "uid": 4,
  "indexUid" :"movie",
  "status": "succeeded",
  "type": "documentAdditionOrUpdate",
  "canceledBy": null,
  "details": {
    …
  },
  "error": null,
  "duration": "PT0.001192S",
  "enqueuedAt": "2022-08-04T12:28:15.159167Z",
  "startedAt": "2022-08-04T12:28:15.161996Z",
  "finishedAt": "2022-08-04T12:28:15.163188Z"
}

If the task is still enqueued or processing, wait a few moments and query the database once again. You may also set up a webhook listener.

When status changes to succeeded, Meilisearch has finished processing your request.

If the task status changes to failed, Meilisearch was not able to fulfill your request. Check the task object’s error field for more information.

Track tasks with custom metadata

You can attach a customMetadata query parameter to document operations. This metadata string appears in task responses and webhook payloads, making it easier to track which batch of data triggered a specific task.

curl \
  -X POST 'MEILISEARCH_URL/indexes/movies/documents?customMetadata=batch-2026-03-daily-update' \
  -H 'Content-Type: application/json' \
  --data-binary '[
    { "id": 1, "title": "Movie One" },
    { "id": 2, "title": "Movie Two" }
  ]'

The summarized task object returned by this request includes the metadata you specified:

{
  "taskUid": 12,
  "indexUid": "movies",
  "status": "enqueued",
  "type": "documentAdditionOrUpdate",
  "customMetadata": "batch-2026-03-daily-update",
  "enqueuedAt": "2026-03-21T10:00:00.000000Z"
}

This is particularly useful when combined with webhooks, as the metadata lets you correlate incoming webhook notifications with specific data pipelines or scheduled imports.

Conclusion

You have seen what happens when an API request adds a task to the task queue, and how to check the status of that task. Consult the task API reference and the asynchronous operations explanation for more information on how tasks work.