APIs supporting bulk operations may trigger long-running or computationally expensive tasks. In these cases, calling the API will schedule an asynchronous task and return a response containing the task ID to be used to retrieve the status of the task.

The get task API (GET /api/v1/tasks/{taskId}) response will contain the status field as well as the failures field, if any operations failed. Results are stored for up to 3 days.

Note that asynchronous tasks are not guaranteed to be run in order. In other words, if you need your tasks to execute in a certain order, you should start a task only after the prerequisite task(s) have finished.

Idempotency key

This header allows for bulk operations to be safely retried without accidentally performing the same operation. Subsequent requests with the same key and request body will return the same task id, or validation errors. Reusing the idempotency key with a different request will result in an error.

When calling bulk operation APIs, you must include the idempotency-key header in your requests. The value of this header should be unique for each request and is provided by the client. We suggest using UUIDs as the value.