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

Summarized task object

When an API request triggers an asynchronous process, Meilisearch returns a summarized task object. This object contains the following fields:

Field	Type	Description
taskUid	Integer	Unique sequential identifier
indexUid	String	Unique index identifier (always null for global tasks)
status	String	Status of the task. Value is enqueued
type	String	Type of task
enqueuedAt	String	Represents the date and time in the RFC 3339 (opens new window) format when the task has been enqueued

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

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	* (all tasks)	Filter tasks by their enqueuedAt field
beforeStartedAt	* (all tasks)	Filter tasks by their startedAt field
beforeFinishedAt	* (all tasks)	Filter tasks by their finishedAt field
afterEnqueuedAt	* (all tasks)	Filter tasks by their enqueuedAt field
afterStartedAt	* (all tasks)	Filter tasks by their startedAt field
afterFinishedAt	* (all tasks)	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'

client.getTasks()

client.get_tasks()

$client->getTasks();

client.getTasks();

client.tasks

client.GetTasks(nil);

ResourceResults<Task> taskResult = await client.GetTasksAsync();

let tasks: TasksResults = client
  .get_tasks()
  .await
  .unwrap();

client.getTasks() { (result) in
    switch result {
    case .success(let tasks):
        print(tasks)
    case .failure(let error):
        print(error)
    }
}

await client.getTasks();

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'

client.getTask(1)

client.get_task(1)

$client->getTask(1);

client.getTask(1);

client.task(1)

client.GetTask(1);

TaskInfo task = await client.GetTaskAsync(1);

let task: Task = client
  .get_task(1)
  .await
  .unwrap();

client.getTask(taskUid: 1) { (result) in
      switch result {
      case .success(let task):
          print(task)
      case .failure(let error):
          print(error)
      }
  }

await client.getTask(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?{query_parameter}

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. Use beforeEnqueuedAt=* to cancel all tasks
beforeStartedAt	Cancel tasks before a specified startedAt date. Use beforeStartedAt=* to cancel all tasks
afterEnqueuedAt	Cancel tasks after a specified enqueuedAt date. Use afterEnqueuedAt=* to cancel all tasks
afterStartedAt	Cancel tasks after a specified startedAt date. Use afterStartedAt=* to cancel all tasks

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'

client.cancelTasks({ uids: [1, 2] })

client.cancel_tasks({'uids': ['1', '2']})

$client->cancelTasks((new CancelTasksQuery())->setUids([1, 2]));

CancelTasksQuery query = new CancelTasksQuery().setUids(new int[] {1, 2})
client.cancelTasks(query);

client.cancel_tasks(uids: [1, 2])

client.CancelTasks(&meilisearch.CancelTasksQuery{
  UIDS: []int64{1, 2},
});

await client.CancelTasksAsync(new CancelTasksQuery { Uids = new List<int> { 1, 2 } });

let mut query = tasks::TasksCancelQuery::new(&client);
query.with_uids([1, 2]);

let res = client.cancel_task_with(&query).await.unwrap();

await client.cancelTasks(params: CancelTasksQuery(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?{query_parameter}

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. Use beforeEnqueuedAt=* to delete all tasks
beforeStartedAt	Delete tasks before a specified startedAt date. Use beforeStartedAt=* to delete all tasks
beforeFinishedAt	Delete tasks before a specified finishedAt date. Use beforeFinishedAt=* to delete all tasks
afterEnqueuedAt	Delete tasks after a specified enqueuedAt date. Use afterEnqueuedAt=* to delete all tasks
afterStartedAt	Delete tasks after a specified startedAt date. Use afterStartedAt=* to delete all tasks
afterFinishedAt	Delete tasks after a specified finishedAt date. Use afterFinishedAt=* to delete all tasks

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'

client.deleteTasks({ uids: [1, 2] })

client.delete_tasks({'uids': ['1', '2']})

$client->deleteTasks((new DeleteTasksQuery())->setUids([1, 2]));

DeleteTasksQuery query = new DeleteTasksQuery().setUids(new int[] {1, 2})
client.deleteTasks(query);

client.delete_tasks(uids: [1, 2])

client.DeleteTaks(&meilisearch.DeleteTasksQuery{
  UIDS: []int64{1, 2},
});

await client.DeleteTasksAsync(new DeleteTasksQuery { Uids = new List<int> { 1, 2 } });

let mut query = tasks::TasksDeleteQuery::new(&client);
query.with_uids([1, 2]);

let res = client.delete_tasks_with(&query).await.unwrap();

await client.deleteTasks(params: DeleteTasksQuery(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.