# Tasks

The /tasks route gives information about the progress of asynchronous operations.

# Task object

{
  "uid": 4,
  "indexUid" :"movie",
  "status": "failed",
  "type": "indexDeletion",
  "canceledBy": null,
  "details": {
    "deletedDocuments": 0
  },
  "error": {
    "message": "Index `movie` not found.",
    "code": "index_not_found",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#index_not_found"
  },
  "duration": "PT0.001192S",
  "enqueuedAt": "2022-08-04T12:28:15.159167Z",
  "startedAt": "2022-08-04T12:28:15.161996Z",
  "finishedAt": "2022-08-04T12:28:15.163188Z"
}

# uid

Type: Integer
Description: Unique sequential identifier of the task

NOTE

The task uid is incremented globally.

# indexUid

Type: String
Description: Unique identifier of the targeted index

NOTE

This value is always null for global tasks.

# status

Type: String
Description: Status of the task. Possible values are enqueued, processing, succeeded, failed, and canceled

# type

Type: String
Description: Type of operation performed by the task. Possible values are indexCreation, indexUpdate, indexDeletion, indexSwap, documentAdditionOrUpdate, documentDeletion, settingsUpdate, dumpCreation, taskCancelation, taskDeletion, and snapshotCreation

# canceledBy

Type: Integer
Description: If the task was canceled, canceledBy contains the uid of a taskCancelation task. If the task was not canceled, canceledBy is always null

# details

Type: Object
Description: Detailed information on the task payload. This object's contents depend on the task's type

# documentAdditionOrUpdate

Name Description
receivedDocuments Number of documents received
indexedDocuments Number of documents indexed. null while the task status is enqueued or processing

# documentDeletion

Name Description
providedIds Number of documents queued for deletion
deletedDocuments Number of documents deleted. null while the task status is enqueued or processing

# indexCreation

Name Description
primaryKey Value of the primaryKey field supplied during index creation. null if it was not specified

# indexUpdate

Name Description
primaryKey Value of the primaryKey field supplied during index update. null if it was not specified

# indexDeletion

Name Description
deletedDocuments Number of deleted documents. This should equal the total number of documents in the deleted index. null while the task status is enqueued or processing

# indexSwap

Name Description
swaps Object containing the payload for the indexSwap task

# settingsUpdate

Name Description
rankingRules List of ranking rules
filterableAttributes List of filterable attributes
distinctAttribute The distinct attribute
searchableAttributes List of searchable attributes
displayedAttributes List of displayed attributes
sortableAttributes List of sortable attributes
stopWords List of stop words
synonyms List of synonyms
typoTolerance The typoTolerance object
pagination The pagination object
faceting The faceting object

# dumpCreation

Name Description
dumpUid The generated uid of the dump. This is also the name of the generated dump file. null when the task status is enqueued, processing, canceled, or failed

# taskCancelation

Name Description
matchedTasks The number of matched tasks. If the API key used for the request doesn’t have access to an index, tasks relating to that index will not be included in matchedTasks
canceledTasks The number of tasks successfully canceled. If the task cancelation fails, this will be 0. null when the task status is enqueued or processing
originalFilter The filter used in the cancel task request

NOTE

Task cancelation can be successful and still have canceledTasks: 0. This happens when matchedTasks matches finished tasks (succeeded, failed, or canceled).

# taskDeletion

Name Description
matchedTasks The number of matched tasks. If the API key used for the request doesn’t have access to an index, tasks relating to that index will not be included in matchedTasks
deletedTasks The number of tasks successfully deleted. If the task deletion fails, this will be 0. null when the task status is enqueued or processing
originalFilter The filter used in the delete task request

NOTE

Task deletion can be successful and still have deletedTasks: 0. This happens when matchedTasks matches enqueued or processing tasks.

# snapshotCreation

The details object is set to null for snapshotCreation tasks.

# error

Type: Object
Description: If the task has the failed status, then this object contains the error definition. Otherwise, set to null

Name Description
message A human-readable description of the error
code The error code
type The error type
link A link to the relevant section of the documentation

# duration

Type: String
Description: The total elapsed time the task spent in the processing state, in ISO 8601 (opens new window) format

# enqueuedAt

Type: String
Description: The date and time when the task was first enqueued, in RFC 3339 (opens new window) format

# startedAt

Type: String
Description: The date and time when the task began processing, in RFC 3339 (opens new window) format

# finishedAt

Type: String
Description: The date and time when the task finished processing, whether failed, succeeded, or canceled, in RFC 3339 (opens new window) format

# Get tasks

GET
/tasks

List all tasks globally, regardless of index. The task objects are contained in the results array.

Tasks are always returned in descending order of uid. This means that by default, the most recently created task objects appear first.

Task results are paginated and can be filtered.

# Query parameters

Query Parameter Default Value Description
limit 20 Number of tasks to return
from uid of the last created task uid of the first task returned
uids * (all uids) Filter tasks by their uid. Separate multiple task uids with a comma (,)
statuses * (all statuses) Filter tasks by their status. Separate multiple task statuses with a comma (,)
types * (all types) Filter tasks by their type. Separate multiple task types with a comma (,)
indexUids * (all indexes) Filter tasks by their indexUid. Separate multiple task indexUids with a comma (,). Case-sensitive
canceledBy N/A Filter tasks by their canceledBy field. Separate multiple task uids with a comma (,)
beforeEnqueuedAt N/A Filter tasks by their enqueuedAt field
beforeStartedAt N/A Filter tasks by their startedAt field
beforeFinishedAt N/A Filter tasks by their finishedAt field
afterEnqueuedAt N/A Filter tasks by their enqueuedAt field
afterStartedAt N/A Filter tasks by their startedAt field
afterFinishedAt N/A Filter tasks by their finishedAt field

# Response

Name Type Description
results Array An array of task objects
limit Integer Number of tasks returned
from Integer uid of the first task 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

curl \
  -X GET 'http://localhost:7700/tasks'

# Response: 200 Ok

{
  "results":[
    {
      "uid":1,
      "indexUid":"movies_reviews",
      "status":"failed",
      "type":"documentAdditionOrUpdate",
      "canceledBy": null,
      "details":{
        "receivedDocuments":100,
        "indexedDocuments":0
      },
      "error": null,
      "duration":null,
      "enqueuedAt":"2021-08-12T10:00:00.000000Z",
      "startedAt":null,
      "finishedAt":null
    },
    {
      "uid":0,
      "indexUid":"movies",
      "status":"succeeded",
      "type":"documentAdditionOrUpdate",
      "canceledBy": null,
      "details":{
        "receivedDocuments":100,
        "indexedDocuments":100
      },
      "error": null,
      "duration":"PT16S",
      "enqueuedAt":"2021-08-11T09:25:53.000000Z",
      "startedAt":"2021-08-11T10:03:00.000000Z",
      "finishedAt":"2021-08-11T10:03:16.000000Z"
    }
  ],
  "limit": 20,
  "from": 1,
  "next":null
}

# Get one task

GET
/tasks/{task_uid}

Get a single task.

NOTE

If you try retrieving a deleted task, Meilisearch will return a task_not_found error.

# Path parameters

Name Type Description
task_uid * String uid of the requested task

# Example

curl \
  -X GET 'http://localhost:7700/tasks/1'

# Response: 200 Ok

{
  "uid":1,
  "indexUid":"movies",
  "status":"succeeded",
  "type":"settingsUpdate",
  "canceledBy": null,
  "details":{
    "rankingRules":[
      "typo",
      "ranking:desc",
      "words",
      "proximity",
      "attribute",
      "exactness"
    ]
  },
  "error": null,
  "duration":"PT1S",
  "enqueuedAt":"2021-08-10T14:29:17.000000Z",
  "startedAt":"2021-08-10T14:29:18.000000Z",
  "finishedAt":"2021-08-10T14:29:19.000000Z"
}

# Cancel tasks

POST
/tasks/cancel?{task_uid}

Cancel any number of enqueued or processing tasks based on their uid, status, type, indexUid, or the date at which they were enqueued, processed, or completed.

Task cancelation is an atomic transaction: either all tasks are successfully canceled or none are.

WARNING

To prevent users from accidentally canceling all enqueued and processing tasks, Meilisearch throws the missing_task_filters error if this route is used without any filters (POST /tasks/cancel).

Did you know?

You can also cancel taskCancelation type tasks as long as they are in the enqueued or processing state. This is possible because taskCancelation type tasks are processed in reverse order, such that the last one you enqueue will be processed first.

# Query parameters

A valid uids, statuses, types, indexUids, or date(beforeXAt or afterXAt) parameter is required.

Query Parameter Description
uids Cancel tasks based on uid. Separate multiple uids with a comma (,). Use uids=* for all uids
statuses Cancel tasks based on status. Separate multiple statuses with a comma (,). Use statuses=* for all statuses
types Cancel tasks based on type. Separate multiple types with a comma (,). Use types=* for all types
indexUids Cancel tasks based on indexUid. Separate multiple uids with a comma (,). Use indexUids=* for all indexUids. Case-sensitive
beforeEnqueuedAt Cancel tasks before a specified enqueuedAt date
beforeStartedAt Cancel tasks before a specified startedAt date
afterEnqueuedAt Cancel tasks after a specified enqueuedAt date
afterStartedAt Cancel tasks after a specified startedAt date

NOTE

Date filters are equivalent to < or > operations. At this time, there is no way to perform a or operations with a date filter.

To learn more about filtering tasks, refer to our dedicated guide.

# Example

curl \
  -X POST 'http://localhost:7700/tasks/cancel?uids=1,2'

# Response: 200 Ok

{
  "taskUid": 3,
  "indexUid": null,
  "status": "enqueued",
  "type": "taskCancelation",
  "enqueuedAt": "2021-08-12T10:00:00.000000Z"
}

NOTE

Since taskCancelation is a global task, its indexUid is always null.

You can use this taskUid to get more details on the status of the task.

# Cancel all tasks

You can cancel all processing and enqueued tasks using the following filter:

POST
/tasks/cancel?statuses=processing,enqueued

The API key used must have access to all indexes ("indexes": [*]) and the task.cancel action.

# Delete tasks

DELETE
/tasks?{task_uid}

Delete a finished (succeeded, failed, or canceled) task based on uid, status, type, indexUid, canceledBy, or date. Task deletion is an atomic transaction: either all tasks are successfully deleted, or none are.

WARNING

To prevent users from accidentally deleting the entire task history, Meilisearch throws the missing_task_filters error if this route is used without any filters (DELETE /tasks).

# Query parameters

A valid uids, statuses, types, indexUids, canceledBy, or date(beforeXAt or afterXAt) parameter is required.

Query Parameter Description
uids Delete tasks based on uid. Separate multiple uids with a comma (,). Use uids=* for all uids
statuses Delete tasks based on status. Separate multiple statuses with a comma (,). Use statuses=* for all statuses
types Delete tasks based on type. Separate multiple types with a comma (,). Use types=* for all types
indexUids Delete tasks based on indexUid. Separate multiple uids with a comma (,). Use indexUids=* for all indexUids. Case-sensitive
canceledBy Delete tasks based on the canceledBy field
beforeEnqueuedAt Delete tasks before a specified enqueuedAt date
beforeStartedAt Delete tasks before a specified startedAt date
beforeFinishedAt Delete tasks before a specified finishedAt date
afterEnqueuedAt Delete tasks after a specified enqueuedAt date
afterStartedAt Delete tasks after a specified startedAt date
afterFinishedAt Delete tasks after a specified finishedAt date

NOTE

Date filters are equivalent to < or > operations. At this time, there is no way to perform a or operations with a date filter.

To learn more about filtering tasks, refer to our dedicated guide.

# Example

curl \
  -X DELETE 'http://localhost:7700/tasks?uids=1,2'

# Response: 200 Ok

{
  "taskUid": 3,
  "indexUid": null,
  "status": "enqueued",
  "type": "taskDeletion",
  "enqueuedAt": "2021-08-12T10:00:00.000000Z"
}

NOTE

Since taskDeletion is a global task, its indexUid is always null.

You can use this taskUid to get more details on the status of the task.

# Delete all tasks

You can delete all finished tasks by using the following filter:

DELETE
/tasks?statuses=failed,canceled,succeeded

The API key used must have access to all indexes ("indexes": [*]) and the task.delete action.