> ## Documentation Index > Fetch the complete documentation index at: https://www.meilisearch.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # List batches > Meilisearch groups compatible tasks ([asynchronous operations](https://www.meilisearch.com/docs/learn/async/asynchronous_operations)) into batches for efficient processing. For example, multiple document additions to the same index may be batched together. List batches to monitor their progress and performance. 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 and can be filtered with query parameters. ## OpenAPI ````yaml /assets/open-api/meilisearch-openapi-mintlify.json get /batches openapi: 3.1.0 info: title: meilisearch description: Meilisearch HTTP server contact: name: Quentin de Quelen email: quentin@dequelen.me license: name: MIT identifier: MIT version: 1.41.0 servers: - url: http://localhost:7700 description: Local server. security: [] tags: - name: Stats description: >- Stats gives extended information and metrics about indexes and the Meilisearch database. - name: Health description: >- The health check endpoint enables you to periodically test the health of your Meilisearch instance. - name: Version description: Returns the version of the running Meilisearch instance. - name: Backups description: >- Meilisearch offers two types of backups: snapshots and dumps. Snapshots are mainly intended as a safeguard, while dumps are useful when migrating Meilisearch. - name: Export description: >- Export documents and settings from this instance to a remote Meilisearch server. - name: Async task management description: >- Routes for listing and managing batches and tasks (asynchronous operations). - name: Chats description: The `/chats` route allows you to manage chat workspaces. - name: Tasks description: >- The tasks route gives information about the progress of the [asynchronous operations](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html). - name: Batches description: >- Meilisearch groups compatible tasks ([asynchronous operations](https://www.meilisearch.com/docs/learn/async/asynchronous_operations)) into batches for efficient processing. For example, multiple document additions to the same index may be batched together. The /batches routes give information about the progress of these batches and let you monitor batch progress and performance. - name: Indexes description: >- An index is an entity that gathers a set of [documents](https://www.meilisearch.com/docs/learn/getting_started/documents) with its own [settings](https://www.meilisearch.com/docs/reference/api/settings). Learn more about indexes. - name: Documents description: >- Documents are objects composed of fields that can store any type of data. Each field contains an attribute and its associated value. Documents are stored inside [indexes](https://www.meilisearch.com/docs/learn/getting_started/indexes). - name: Facet Search description: >- The `/facet-search` route allows you to search for facet values. Facet search supports prefix search and typo tolerance. The returned hits are sorted lexicographically in ascending order. You can configure how facets are sorted using the sortFacetValuesBy property of the faceting index settings. - name: Similar documents description: >- The /similar route uses AI-powered search to return a number of documents similar to a target document. Meilisearch exposes two routes for retrieving similar documents: POST and GET. In the majority of cases, POST will offer better performance and ease of use. - name: Settings description: >- Configure search and index behavior. Update all settings at once via PATCH /indexes/{indexUid}/settings, or use a sub-route to get, update, or reset a single setting. - name: Search description: >- Meilisearch exposes two routes to perform searches: - A POST route: this is the preferred route when using API authentication, as it allows [preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) caching and better performance. - A GET route: the usage of this route is discouraged, unless you have good reason to do otherwise (specific caching abilities for example) externalDocs: url: https://www.meilisearch.com/docs/reference/api/search description: Search API reference - name: Keys description: >- Manage API `keys` for a Meilisearch instance. Each key has a given set of permissions. You must have the master key or the default admin key to access the keys route. More information about the keys and their rights. Accessing any route under `/keys` without having set a master key will result in an error. - name: Logs description: >- Everything about retrieving or customizing logs. Currently [experimental](https://www.meilisearch.com/docs/learn/experimental/overview). - name: Multi-search description: >- The `/multi-search` route allows you to perform multiple search queries on one or more indexes by bundling them into a single HTTP request. Multi-search is also known as federated search. - name: Experimental features description: >- The `/experimental-features` route allows you to activate or deactivate some of Meilisearch's experimental features. This route is **synchronous**. This means that no task object will be returned, and any activated or deactivated features will be made available or unavailable immediately. - name: Network description: >- The `/network` route allows you to describe the topology of a network of Meilisearch instances. This route is **synchronous**. This means that no task object will be returned, and any change to the network will be made available immediately. - name: Webhooks description: >- The `/webhooks` route allows you to register endpoints to be called once tasks are processed. - name: Dynamic search rules description: >- The `/dynamic-search-rules` route allows you to configure dynamic search rules. paths: /batches: get: tags: - Async task management summary: List batches description: >- Meilisearch groups compatible tasks ([asynchronous operations](https://www.meilisearch.com/docs/learn/async/asynchronous_operations)) into batches for efficient processing. For example, multiple document additions to the same index may be batched together. List batches to monitor their progress and performance. 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 and can be filtered with query parameters. operationId: get_batches parameters: - name: limit in: query description: Maximum number of batches to return. required: false schema: type: integer format: u-int32 default: 20 minimum: 0 example: 12 - name: from in: query description: '`uid` of the first batch returned.' required: false schema: type: integer format: u-int32 minimum: 0 example: 12421 - name: reverse in: query description: >- If `true`, returns results in the reverse order, from oldest to most recent. required: false schema: type: boolean example: true - name: batchUids in: query description: |- Permits to filter tasks by their batch uid. By default, when the `batchUids` query parameter is not set, all task uids are returned. It's possible to specify several batch uids by separating them with the `,` character. required: false schema: type: integer format: u-int32 minimum: 0 example: 12421 - name: uids in: query description: >- Permits to filter tasks by their uid. By default, when the uids query parameter is not set, all task uids are returned. It's possible to specify several uids by separating them with the `,` character. required: false schema: type: array items: type: integer format: u-int32 minimum: 0 example: - 231 - 423 - 598 - name: canceledBy in: query description: >- Permits to filter tasks using the uid of the task that canceled them. It's possible to specify several task uids by separating them with the `,` character. required: false schema: type: array items: type: integer format: u-int32 minimum: 0 example: - 374 - name: types in: query description: >- Permits to filter tasks by their related type. By default, when `types` query parameter is not set, all task types are returned. It's possible to specify several types by separating them with the `,` character. required: false schema: type: array items: type: string example: - documentAdditionOrUpdate - name: statuses in: query description: |- Permits to filter tasks by their status. By default, when `statuses` query parameter is not set, all task statuses are returned. It's possible to specify several statuses by separating them with the `,` character. required: false schema: type: array items: $ref: '#/components/schemas/Status' example: - succeeded - failed - canceled - enqueued - processing - name: indexUids in: query description: >- Permits to filter tasks by their related index. By default, when `indexUids` query parameter is not set, the tasks of all the indexes are returned. It is possible to specify several indexes by separating them with the `,` character. required: false schema: type: array items: type: string example: - movies - theater - name: afterEnqueuedAt in: query description: >- Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued after the given date. Supports RFC 3339 date format. required: false schema: type: string example: '2024-08-08T16:37:09.971Z' - name: beforeEnqueuedAt in: query description: >- Permits to filter tasks based on their enqueuedAt time. Matches tasks enqueued before the given date. Supports RFC 3339 date format. required: false schema: type: string example: '2024-08-08T16:37:09.971Z' - name: afterStartedAt in: query description: |- Permits to filter tasks based on their startedAt time. Matches tasks started after the given date. Supports RFC 3339 date format. required: false schema: type: string example: '2024-08-08T16:37:09.971Z' - name: beforeStartedAt in: query description: |- Permits to filter tasks based on their startedAt time. Matches tasks started before the given date. Supports RFC 3339 date format. required: false schema: type: string example: '2024-08-08T16:37:09.971Z' - name: afterFinishedAt in: query description: >- Permits to filter tasks based on their finishedAt time. Matches tasks finished after the given date. Supports RFC 3339 date format. required: false schema: type: string example: '2024-08-08T16:37:09.971Z' - name: beforeFinishedAt in: query description: >- Permits to filter tasks based on their finishedAt time. Matches tasks finished before the given date. Supports RFC 3339 date format. required: false schema: type: string example: '2024-08-08T16:37:09.971Z' responses: '200': description: Returns the batches. content: application/json: schema: $ref: '#/components/schemas/AllBatches' example: results: - uid: 2 details: stopWords: - of - the progress: null stats: totalNbTasks: 1 status: succeeded: 1 types: settingsUpdate: 1 indexUids: INDEX_NAME: 1 duration: PT0.110083S startedAt: '2024-12-10T15:49:04.995321Z' finishedAt: '2024-12-10T15:49:05.105404Z' total: 1 limit: 20 from: 1 next: null '401': description: The authorization header is missing. content: application/json: schema: $ref: '#/components/schemas/ResponseError' example: message: >- The Authorization header is missing. It must use the bearer authorization method. code: missing_authorization_header type: auth link: >- https://docs.meilisearch.com/errors#missing_authorization_header security: - Bearer: - tasks.get - tasks.* - '*' x-codeSamples: - lang: cURL source: |- curl \ -X GET 'http://MEILISEARCH_URL/batches' - lang: JS source: client.batches.getBatches(); - lang: PHP source: $client->getBatches(); - lang: Python source: client.get_batches() - lang: Ruby source: client.batches - lang: Go source: client.GetBatches(); - lang: Rust source: >- 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(); components: schemas: Status: type: string description: The status of a task. enum: - enqueued - processing - succeeded - failed - canceled example: processing AllBatches: type: object description: Response containing a paginated list of batches required: - results - total - limit properties: results: type: array items: $ref: '#/components/schemas/BatchView' description: Array of batch objects total: type: integer format: u-int64 description: Total number of batches minimum: 0 limit: type: integer format: u-int32 description: Maximum number of batches returned minimum: 0 from: type: - integer - 'null' format: u-int32 description: The first batch uid returned minimum: 0 next: type: - integer - 'null' format: u-int32 description: Value to send in from to fetch the next slice of results minimum: 0 ResponseError: type: object required: - message - code - type - link properties: message: type: string description: The error message. code: $ref: '#/components/schemas/Code' description: The error code. type: $ref: '#/components/schemas/ErrorType' description: The error type. link: type: string description: A link to the documentation about this specific error. BatchView: type: object description: Represents a batch of tasks that were processed together. required: - uid - details - stats properties: uid: $ref: '#/components/schemas/u32' description: >- The unique sequential identifier assigned to this batch. Batch UIDs are assigned in order of creation and can be used to retrieve specific batch information or correlate tasks that were processed together. progress: oneOf: - type: 'null' - $ref: '#/components/schemas/ProgressView' description: >- Real-time progress information for the batch if it's currently being processed. Contains details about which step is executing and the percentage of completion. This is `null` for completed batches. details: type: object description: |- Aggregated details from all tasks in this batch. For example, if the batch contains multiple document addition tasks, this will show the total number of documents received and indexed across all tasks. stats: $ref: '#/components/schemas/BatchStatsView' description: >- Statistical information about the batch, including the number of tasks by status, the types of tasks included, and the indexes affected. Useful for understanding the composition and outcome of the batch. duration: type: - string - 'null' description: >- The total time spent processing this batch, formatted as an ISO-8601 duration (e.g., `PT2.5S` for 2.5 seconds). This is `null` for batches that haven't finished processing yet. startedAt: type: string format: date-time description: >- The timestamp when Meilisearch began processing this batch, formatted as an RFC 3339 date-time string. All batches have a start time as it's set when processing begins. finishedAt: type: - string - 'null' format: date-time description: |- The timestamp when this batch finished processing, formatted as an RFC 3339 date-time string. This is `null` for batches that are still being processed. batchStrategy: type: string description: >- Explains why the batch was finalized and stopped accepting more tasks. Common reasons include reaching the maximum batch size, encountering incompatible tasks, or processing being explicitly triggered. Code: type: string enum: - api_key_already_exists - api_key_not_found - bad_parameter - bad_request - database_size_limit_reached - document_not_found - dump_already_processing - dump_not_found - dump_process_failed - duplicate_index_found - immutable_api_key_actions - immutable_api_key_created_at - immutable_api_key_expires_at - immutable_api_key_indexes - immutable_api_key_key - immutable_api_key_uid - immutable_api_key_updated_at - immutable_index_created_at - immutable_index_updated_at - import_task_already_received - import_task_unknown_remote - receive_import_finished_unknown_remote - import_task_without_network_task - index_already_exists - index_creation_failed - index_not_found - index_primary_key_already_exists - index_primary_key_multiple_candidates_found - index_primary_key_no_candidate_found - internal - invalid_api_key - invalid_api_key_actions - invalid_api_key_description - invalid_api_key_expires_at - invalid_api_key_indexes - invalid_api_key_limit - invalid_api_key_name - invalid_api_key_offset - invalid_api_key_uid - invalid_content_type - invalid_document_csv_delimiter - invalid_document_fields - invalid_document_retrieve_vectors - missing_document_filter - missing_document_edition_function - inconsistent_document_change_headers - invalid_document_filter - invalid_document_sort - invalid_document_geo_field - invalid_document_geojson_field - invalid_header_value - invalid_vector_dimensions - invalid_vectors_type - invalid_document_id - invalid_document_ids - invalid_document_limit - invalid_document_offset - invalid_search_embedder - invalid_similar_embedder - invalid_search_hybrid_query - invalid_index_limit - invalid_index_offset - invalid_index_primary_key - invalid_index_custom_metadata - invalid_skip_creation - invalid_index_uid - invalid_multi_search_facets - invalid_multi_search_facets_by_index - invalid_multi_search_facet_order - invalid_multi_search_query_personalization - invalid_multi_search_query_show_performance_details - invalid_multi_search_federated - invalid_multi_search_federation_options - invalid_multi_search_max_values_per_facet - invalid_multi_search_merge_facets - invalid_multi_search_query_facets - invalid_multi_search_distinct - invalid_multi_search_query_pagination - invalid_multi_search_query_ranking_rules - invalid_multi_search_query_position - invalid_multi_search_remote - invalid_multi_search_weight - invalid_network_leader - invalid_network_remotes - invalid_network_shards - invalid_network_self - invalid_network_search_api_key - invalid_network_write_api_key - invalid_network_url - invalid_search_attributes_to_search_on - invalid_search_attributes_to_crop - invalid_search_attributes_to_highlight - invalid_similar_attributes_to_retrieve - invalid_similar_retrieve_vectors - invalid_search_attributes_to_retrieve - invalid_search_ranking_score_threshold - invalid_similar_ranking_score_threshold - invalid_search_retrieve_vectors - invalid_search_crop_length - invalid_search_crop_marker - invalid_search_facets - invalid_search_semantic_ratio - invalid_search_locales - invalid_facet_search_exhaustive_facet_count - invalid_facet_search_facet_name - invalid_similar_id - invalid_search_filter - invalid_similar_filter - invalid_search_highlight_post_tag - invalid_search_highlight_pre_tag - invalid_search_hits_per_page - invalid_similar_limit - invalid_search_limit - invalid_search_matching_strategy - invalid_similar_offset - invalid_search_offset - invalid_search_page - invalid_search_q - invalid_facet_search_query - invalid_facet_search_name - facet_search_disabled - invalid_search_vector - invalid_search_media - invalid_search_show_matches_position - invalid_search_show_ranking_score - invalid_similar_show_ranking_score - invalid_search_show_ranking_score_details - invalid_search_show_performance_details - invalid_search_use_network - invalid_similar_show_ranking_score_details - invalid_similar_show_performance_details - invalid_search_sort - invalid_search_distinct - invalid_search_personalize - invalid_search_personalize_user_context - invalid_search_media_and_vector - invalid_settings_displayed_attributes - invalid_settings_distinct_attribute - invalid_settings_proximity_precision - invalid_settings_facet_search - invalid_settings_prefix_search - invalid_settings_faceting - invalid_settings_filterable_attributes - invalid_settings_foreign_keys - invalid_settings_pagination - invalid_settings_search_cutoff_ms - invalid_settings_embedders - invalid_settings_ranking_rules - invalid_settings_searchable_attributes - invalid_settings_sortable_attributes - invalid_settings_stop_words - invalid_settings_non_separator_tokens - invalid_settings_separator_tokens - invalid_settings_dictionary - invalid_settings_synonyms - invalid_settings_typo_tolerance - invalid_settings_localized_attributes - invalid_state - invalid_store_file - invalid_swap_duplicate_index_found - invalid_swap_indexes - invalid_swap_rename - invalid_task_after_enqueued_at - invalid_task_after_finished_at - invalid_task_after_started_at - invalid_task_before_enqueued_at - invalid_task_before_finished_at - invalid_task_before_started_at - invalid_task_canceled_by - invalid_task_from - invalid_task_limit - invalid_task_reverse - invalid_task_statuses - invalid_task_types - invalid_task_uids - invalid_batch_uids - io_error - feature_not_enabled - malformed_payload - max_fields_limit_exceeded - missing_api_key_actions - missing_api_key_expires_at - missing_api_key_indexes - missing_authorization_header - missing_content_type - missing_document_id - missing_facet_search_facet_name - missing_index_uid - missing_master_key - missing_network_url - missing_payload - missing_search_hybrid - missing_swap_indexes - missing_task_filters - network_version_mismatch - no_space_left_on_device - not_leader - payload_too_large - remote_bad_response - remote_bad_request - remote_could_not_send_request - remote_invalid_api_key - remote_remote_error - remote_timeout - too_many_search_requests - task_not_found - task_file_not_found - batch_not_found - too_many_open_files - too_many_vectors - unexpected_network_previous_remotes - network_version_too_old - unprocessed_network_task - unretrievable_document - unretrievable_error_code - unsupported_media_type - invalid_s3_snapshot_request - invalid_s3_snapshot_parameters - s3_snapshot_server_error - vector_embedding_error - not_found_similar_id - invalid_document_edition_context - invalid_document_edition_function_filter - edit_documents_by_function_error - invalid_settings_index_chat - invalid_export_url - invalid_export_api_key - invalid_export_payload_size - invalid_export_indexes_patterns - invalid_export_index_filter - invalid_export_index_override_settings - unimplemented_external_function_calling - unimplemented_non_streaming_chat_completions - unimplemented_multi_choice_chat_completions - chat_not_found - invalid_chat_setting_document_template - invalid_chat_completion_org_id - invalid_chat_completion_project_id - invalid_chat_completion_api_version - invalid_chat_completion_deployment_id - invalid_chat_completion_source - invalid_chat_completion_base_api - invalid_chat_completion_api_key - invalid_chat_completion_prompts - invalid_chat_completion_system_prompt - invalid_chat_completion_search_description_prompt - invalid_chat_completion_search_query_param_prompt - invalid_chat_completion_search_filter_param_prompt - invalid_chat_completion_search_index_uid_param_prompt - invalid_chat_completion_pre_query_prompt - invalid_index_fields_filter - invalid_index_fields_filter_attribute_patterns - invalid_index_fields_filter_displayed - invalid_index_fields_filter_searchable - invalid_index_fields_filter_sortable - invalid_index_fields_filter_distinct - invalid_index_fields_filter_ranking_rule - invalid_index_fields_filter_filterable - requires_enterprise_edition - invalid_webhooks - invalid_webhook_url - invalid_webhook_headers - immutable_webhook - invalid_webhook_uuid - webhook_not_found - immutable_webhook_uuid - immutable_webhook_is_editable - invalid_dynamic_search_rule_offset - invalid_dynamic_search_rule_limit - invalid_dynamic_search_rule_filter - invalid_dynamic_search_rule_description - invalid_dynamic_search_rule_priority - invalid_dynamic_search_rule_active - invalid_dynamic_search_rule_conditions - invalid_dynamic_search_rule_actions - invalid_dynamic_search_rule_filter_attribute_patterns - invalid_dynamic_search_rule_filter_active - dynamic_search_rule_not_found ErrorType: type: string enum: - internal - invalid_request - auth - system u32: type: integer format: u-int32 minimum: 0 ProgressView: type: object description: |- Real-time progress information for a batch or task that is currently being processed. Use this to display progress bars or status updates to users. required: - steps - percentage properties: steps: type: array items: $ref: '#/components/schemas/ProgressStepView' description: |- A hierarchical list of processing steps currently being executed. Steps are listed from outermost to innermost, with each step representing a more granular operation within its parent step. percentage: type: number format: float description: |- The overall completion percentage of the operation (0.0 to 100.0). This is calculated by combining the progress of all nested steps, weighted by their relative importance. BatchStatsView: allOf: - $ref: '#/components/schemas/BatchStats' description: |- Core batch statistics including the total number of tasks, counts by status (succeeded, failed, canceled), task types included, and which indexes were affected by this batch. - type: object properties: embedderRequests: $ref: '#/components/schemas/EmbedderStatsView' description: >- Statistics about AI embedder API requests made during batch processing. Includes total requests, successful/failed counts, and response times. Only present when the batch involved vector embedding operations. description: >- Provides comprehensive statistics about a batch's execution. Includes task counts, status breakdowns, and AI embedder usage. This information is useful for monitoring system performance and understanding batch composition. ProgressStepView: type: object description: |- Information about a single processing step within a batch or task. Each step has a name, current progress, and total items to process. required: - currentStep - finished - total properties: currentStep: type: string description: |- A human-readable name describing what this processing step is doing. Examples include "indexing documents", "computing embeddings", "building word cache", etc. finished: type: integer format: u-int32 description: |- The number of items that have been processed so far in this step. Compare with `total` to calculate the percentage complete for this specific step. minimum: 0 total: type: integer format: u-int32 description: |- The total number of items to process in this step. When `finished` equals `total`, this step is complete and processing moves to the next step. minimum: 0 BatchStats: type: object description: Statistics for a batch of tasks required: - totalNbTasks - status - types - indexUids properties: totalNbTasks: $ref: '#/components/schemas/u32' description: Total number of tasks in the batch status: type: object description: Count of tasks by status additionalProperties: type: integer format: u-int32 minimum: 0 propertyNames: type: string description: The status of a task. enum: - enqueued - processing - succeeded - failed - canceled example: processing types: type: object description: Count of tasks by type additionalProperties: type: integer format: u-int32 minimum: 0 propertyNames: type: string description: The type of the task. enum: - documentAdditionOrUpdate - documentEdition - documentDeletion - settingsUpdate - indexCreation - indexDeletion - indexUpdate - indexSwap - taskCancelation - taskDeletion - dumpCreation - snapshotCreation - export - upgradeDatabase - indexCompaction - networkTopologyChange example: documentAdditionOrUpdate indexUids: type: object description: Count of tasks by index UID additionalProperties: type: integer format: u-int32 minimum: 0 propertyNames: type: string progressTrace: type: object description: Detailed progress trace information additionalProperties: {} propertyNames: type: string writeChannelCongestion: type: - object - 'null' description: Write channel congestion metrics additionalProperties: {} propertyNames: type: string internalDatabaseSizes: type: object description: Internal database size information additionalProperties: {} propertyNames: type: string EmbedderStatsView: type: object description: Statistics for embedder requests required: - total - failed properties: total: type: integer description: Total number of embedder requests minimum: 0 failed: type: integer description: Number of failed embedder requests minimum: 0 lastError: type: - string - 'null' description: Last error message from the embedder securitySchemes: Bearer: type: http scheme: bearer bearerFormat: Uuidv4, string or JWT description: >- An API key is a token that you provide when making API calls. Read more about [how to secure your project](https://www.meilisearch.com/docs/learn/security/basic_security). Include the API key to the `Authorization` header, for instance: ```bash -H 'Authorization: Bearer 6436fc5237b0d6e0d64253fbaac21d135012ecf1' ``` If you use a SDK, ensure you instantiate the client with the API key, for instance with [JS SDK](https://github.com/meilisearch/meilisearch-js): ```js const client = new Meilisearch({ host: 'MEILISEARCH_URL', apiKey: '6436fc5237b0d6e0d64253fbaac21d135012ecf1' }); ``` ````