The Background Tasks API allows you to create and manage tasks that process data items. Tasks run in the background, so they don't block the user's ability to work on their site while items are processed.
Each task has a different type, which determines the kind of processing the task performs on the items of the specified collection. You can create tasks to:
It's important to note the following points before starting to code:
UPDATE_PUBLISH_STATUS
, the collection must have the Publish plugin to control item visibility.This article presents possible sample flows that you can support. This can be a helpful jumping-off point as you plan your implementation.
Note: Learn more about querying data collections using API Query Language.
On a data collection that has the Publish plugin, create a task to publish all special-edition holiday items at the specified time:
Call Create Task and specify the following parameters:
{
"task": {
"type": "UPDATE_PUBLISH_STATUS",
"updatePublishStatusOptions": {
"dataCollectionId": "products",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
},
"operation": "SCHEDULE_PUBLISHED_STATUS",
"schedulePublishedStatusOptions": {
"date": "2024-10-24T10:00:00Z"
}
}
}
}
The method returns the following response:
{
"task": {
"id": "b8815393-3bca-4de7-b592-53eeb1465a61",
"type": "UPDATE_PUBLISH_STATUS",
"status": "NEW",
"startedAt": "2024-09-05T10:34:59.507Z",
"estimatedItemCount": 5,
"itemsSucceeded": 0,
"itemsFailed": 0,
"failures": [],
"updatePublishStatusOptions": {
"dataCollectionId": "Products",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
},
"operation": "SCHEDULE_PUBLISHED_STATUS",
"schedulePublishedStatusOptions": {
"date": "2024-10-24T10:00:00Z"
}
}
}
}
At any point, you can check the task status by calling the Get Task method with the task ID.
The method returns a response such as:
{
"task": {
"id": "b8815393-3bca-4de7-b592-53eeb1465a61",
"type": "SCHEDULE_PUBLISHED_STATUS",
"status": "FAILED",
"startedAt": "2024-09-05T10:34:59.507Z",
"finishedAt": "2024-09-05T10:35:03.654Z",
"estimatedItemCount": 4,
"itemsSucceeded": 0,
"itemsFailed": 4,
"failures": [
{
"code": 404,
"description": "Collection not found.",
"data": {
"dataCollectionId": "Products"
}
}
],
"updatePublishStatusOptions": {
"dataCollectionId": "Products",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
},
"operation": "SCHEDULE_PUBLISHED_STATUS",
"schedulePublishedStatusOptions": {
"date": "2024-10-24T10:00:00Z"
}
}
}
}
Create a task to retrieve and delete all products from a specified manufacturer:
Call Create Task and specify the following parameters:
{
"task": {
"type": "DELETE_BY_QUERY",
"deleteByQueryOptions": {
"dataCollectionId": "Products",
"filter": {
"manufacturer": "BadAcme"
}
}
}
}
The method might return the following response:
{
"task": {
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "DELETE_BY_QUERY",
"status": "NEW",
"startedAt": "2024-09-05T10:34:59.507Z",
"estimatedItemCount": 3,
"itemsSucceeded": 0,
"itemsFailed": 0,
"failures": [],
"deleteByQueryOptions": {
"dataCollectionId": "Products",
"filter": {
"manufacturer": "BadAcme"
}
}
}
}
At any point, you can check the task status by calling the Get Task method with the task ID.
The method returns a response such as:
{
"task": {
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "DELETE_BY_QUERY",
"status": "COMPLETED",
"startedAt": "2024-09-05T10:34:59.507Z",
"finishedAt": "2024-09-05T10:35:03.654Z",
"estimatedItemCount": 3,
"itemsSucceeded": 3,
"itemsFailed": 0,
"failures": [],
"deleteByQueryOptions": {
"dataCollectionId": "Products",
"filter": {
"manufacturer": "BadAcme"
}
}
}
}
Background task job that processes data items in bulk.
Task ID.
Task type.
Task status.
Task start time. Empty if the task status is NEW
.
Task finish time. Empty until the task status updates to COMPLETED
or FAILED
.
Number of items whose processing failed.
List of errors generated during the task.
Learn more about Wix Data error codes.
Estimated number of items affected by the task.
Number of items successfully processed so far.
Options for tasks of the type DELETE_BY_QUERY
.
Options for tasks of the type COPY_FIELD_DATA
.
Options for tasks of the type EDIT_FIELD_DATA
.
Options for tasks of the type UPDATE_PUBLISH_STATUS
.
{
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "DELETE_BY_QUERY",
"status": "COMPLETED",
"startedAt": "2024-09-05T10:34:59.507Z",
"finishedAt": "2024-09-05T10:35:03.654Z",
"itemCount": 3,
"itemsSucceeded": 3,
"itemsFailed": 0,
"failures": [],
"deleteByQueryOptions": {
"dataCollectionId": "Items",
"environment": "LIVE",
"filter": {
"altText": {
"$contains": "Placeholder"
}
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Lists all existing tasks.
You can only call this method when authenticated as a Wix app or Wix user identity.
Number of items to load.
Number of items to skip in the current sort order.
Retrieved tasks.
Paging metadata.
curl GET https://wixapis.com/autocms/v1/tasks?paging.offset=5 \
-H 'Authorization: <AUTH>'
{
"tasks": [
{
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "DELETE_BY_QUERY",
"status": "NEW",
"startedAt": "2024-09-05T10:34:59.507Z",
"estimatedItemCount": 3,
"itemsSucceeded": 0,
"itemsFailed": 0,
"failures": [],
"deleteByQueryOptions": {
"dataCollectionId": "Items",
"environment": "LIVE",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
}
}
},
{
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "EDIT_FIELD_DATA",
"status": "NEW",
"startedAt": "2024-09-05T10:34:59.507Z",
"estimatedItemCount": 3,
"itemsSucceeded": 0,
"itemsFailed": 0,
"failures": [],
"editFieldDataOptions": {
"dataCollectionId": "Items",
"environment": "LIVE",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
},
"fieldKey": "tags",
"operations": {
"addItems": ["sale"],
"removeItems": ["outdated"],
"replaceItems": [
{
"from": "Goob",
"to": "Good"
}
],
"removeDuplicates": true
}
}
}
],
"metadata": {
"count": 0,
"offset": 5,
"total": 0
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Creates and runs a new background task.
You can only call this method when authenticated as a Wix app or Wix user identity.
Task to create and run.
Created task.
curl POST https://wixapis.com/autocms/v1/tasks \
-H 'Authorization: <AUTH>' \
-H 'Content-Type: application/json' \
-d '{
"task": {
"type": "DELETE_BY_QUERY",
"deleteByQueryOptions": {
"dataCollectionId": "Items",
"environment": "LIVE",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
},
}
}
}'
{
"task": {
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "DELETE_BY_QUERY",
"status": "NEW",
"startedAt": "2024-09-05T10:34:59.507Z",
"estimatedItemCount": 3,
"itemsSucceeded": 0,
"itemsFailed": 0,
"failures": [],
"deleteByQueryOptions": {
"dataCollectionId": "Items",
"environment": "LIVE",
"filter": {
"altText": {
"$in": "Halloween"
}
}
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Retrieves the specified task.
You can only call this method when authenticated as a Wix app or Wix user identity.
Task ID.
Retrieved task.
curl GET https://wixapis.com/autocms/v1/tasks/097a5564-0fec-4425-8d1e-3e753b48a422 \
-H 'Authorization: <AUTH>'
{
"task": {
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "DELETE_BY_QUERY",
"status": "COMPLETED",
"startedAt": "2024-09-05T10:34:59.507Z",
"finishedAt": "2024-09-05T10:35:03.654Z",
"estimatedItemCount": 3,
"itemsSucceeded": 3,
"itemsFailed": 0,
"failures": [],
"deleteByQueryOptions": {
"dataCollectionId": "Items",
"environment": "LIVE",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
}
}
}
}
This API is subject to change. Bug fixes and new features will be released based on developer feedback throughout the preview period.
Cancels an existing task.
You can only call this method when authenticated as a Wix app or Wix user identity.
Task ID.
Cancelled task.
curl DELETE https://wixapis.com/autocms/v1/tasks/097a5564-0fec-4425-8d1e-3e753b48a422 \
-H 'Authorization: <AUTH>'
{
"task": {
"id": "097a5564-0fec-4425-8d1e-3e753b48a422",
"type": "DELETE_BY_QUERY",
"status": "FAILED",
"startedAt": "2024-09-05T10:34:59.507Z",
"finishedAt": "2024-09-05T10:35:03.654Z",
"estimatedItemCount": 3,
"itemsProcessed": 3,
"itemsFailed": 0,
"failures": [
{
"code": "CANCELLED",
"description": "Cancelled"
}
],
"deleteByQuery": {
"collectionName": "Items",
"filter": {
"holidays": {
"$in": ["Halloween"]
}
}
}
}
}