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.

Task status and limits

Task status values include:

• NOT_STARTED: The task is queued.
• IN_PROGRESS: The task is running.
• FINISHED: The task has completed. Check failures to distinguish complete success from partial success.
• FAILED: The task failed or timed out before completion.

Each tenant (cloud site, identified by cloudId) can have up to 5 non-terminal bulk tasks queued or in progress at the same time. Tasks with NOT_STARTED or IN_PROGRESS status count toward this limit. Tasks with FINISHED or FAILED status do not.

If the limit is reached, new bulk operation requests are rejected with 400 Bad Request and the message Maximum number of tasks reached. Wait for existing tasks to finish before submitting more work. Non-terminal tasks older than 30 minutes are treated as timed out during task-limit checks, which frees capacity for new tasks.

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.