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

    NameDescription
    receivedDocumentsNumber of documents received
    indexedDocumentsNumber of documents indexed. null while the task status is enqueued or processing

    documentDeletion

    NameDescription
    providedIdsNumber of documents queued for deletion
    originalFilterThe filter used to delete documents. null if it was not specified
    deletedDocumentsNumber of documents deleted. null while the task status is enqueued or processing

    indexCreation

    NameDescription
    primaryKeyValue of the primaryKey field supplied during index creation. null if it was not specified

    indexUpdate

    NameDescription
    primaryKeyValue of the primaryKey field supplied during index update. null if it was not specified

    indexDeletion

    NameDescription
    deletedDocumentsNumber 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

    NameDescription
    swapsObject containing the payload for the indexSwap task

    settingsUpdate

    NameDescription
    rankingRulesList of ranking rules
    filterableAttributesList of filterable attributes
    distinctAttributeThe distinct attribute
    searchableAttributesList of searchable attributes
    displayedAttributesList of displayed attributes
    sortableAttributesList of sortable attributes
    stopWordsList of stop words
    synonymsList of synonyms
    typoToleranceThe typoTolerance object
    paginationThe pagination object
    facetingThe faceting object

    dumpCreation

    NameDescription
    dumpUidThe 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

    NameDescription
    matchedTasksThe 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
    canceledTasksThe number of tasks successfully canceled. If the task cancellation fails, this will be 0. null when the task status is enqueued or processing
    originalFilterThe filter used in the cancel task request
    NOTE

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

    taskDeletion

    NameDescription
    matchedTasksThe 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
    deletedTasksThe number of tasks successfully deleted. If the task deletion fails, this will be 0. null when the task status is enqueued or processing
    originalFilterThe 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

    NameDescription
    messageA human-readable description of the error
    codeThe error code
    typeThe error type
    linkA 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 format

    enqueuedAt

    Type: String
    Description: The date and time when the task was first enqueued, in RFC 3339 format

    startedAt

    Type: String
    Description: The date and time when the task began processing, in RFC 3339 format

    finishedAt

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

    Summarized task object

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

    FieldTypeDescription
    taskUidIntegerUnique sequential identifier
    indexUidStringUnique index identifier (always null for global tasks)
    statusStringStatus of the task. Value is enqueued
    typeStringType of task
    enqueuedAtStringRepresents the date and time in the RFC 3339 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 ParameterDefault ValueDescription
    limit20Number of tasks to return
    fromuid of the last created taskuid 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
    canceledByN/AFilter 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

    NameTypeDescription
    resultsArrayAn array of task objects
    totalIntegerTotal number of tasks matching the filter or query
    limitIntegerNumber of tasks returned
    fromIntegeruid of the first task returned
    nextIntegerValue 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"
        }
      ],
      "total": 50,
      "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

    NameTypeDescription
    task_uid *Stringuid 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?{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 cancellation 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 ParameterDescription
    uidsCancel tasks based on uid. Separate multiple uids with a comma (,). Use uids=* for all uids
    statusesCancel tasks based on status. Separate multiple statuses with a comma (,). Use statuses=* for all statuses
    typesCancel tasks based on type. Separate multiple types with a comma (,). Use types=* for all types
    indexUidsCancel tasks based on indexUid. Separate multiple uids with a comma (,). Use indexUids=* for all indexUids. Case-sensitive
    beforeEnqueuedAtCancel tasks before a specified enqueuedAt date. Use beforeEnqueuedAt=* to cancel all tasks
    beforeStartedAtCancel tasks before a specified startedAt date. Use beforeStartedAt=* to cancel all tasks
    afterEnqueuedAtCancel tasks after a specified enqueuedAt date. Use afterEnqueuedAt=* to cancel all tasks
    afterStartedAtCancel 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'

    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 ParameterDescription
    uidsDelete tasks based on uid. Separate multiple uids with a comma (,). Use uids=* for all uids
    statusesDelete tasks based on status. Separate multiple statuses with a comma (,). Use statuses=* for all statuses
    typesDelete tasks based on type. Separate multiple types with a comma (,). Use types=* for all types
    indexUidsDelete tasks based on indexUid. Separate multiple uids with a comma (,). Use indexUids=* for all indexUids. Case-sensitive
    canceledByDelete tasks based on the canceledBy field
    beforeEnqueuedAtDelete tasks before a specified enqueuedAt date. Use beforeEnqueuedAt=* to delete all tasks
    beforeStartedAtDelete tasks before a specified startedAt date. Use beforeStartedAt=* to delete all tasks
    beforeFinishedAtDelete tasks before a specified finishedAt date. Use beforeFinishedAt=* to delete all tasks
    afterEnqueuedAtDelete tasks after a specified enqueuedAt date. Use afterEnqueuedAt=* to delete all tasks
    afterStartedAtDelete tasks after a specified startedAt date. Use afterStartedAt=* to delete all tasks
    afterFinishedAtDelete 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'

    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.