Manage queues and tasks

Cloud Tasks lets you control asynchronous workload execution, pause queue processing, and troubleshoot active task flows. You can configure and maintain your queues and tasks using the Google Cloud console, the Google Cloud CLI, or the Cloud Tasks API.

Before you begin

  1. Make sure that you have an existing Cloud Tasks queue. For more information, see Create Cloud Tasks queues.
  2. Ensure that you have the required Identity and Access Management (IAM) roles to manage queues and tasks, such as Cloud Tasks Admin (roles/cloudtasks.admin), Cloud Tasks Queue Admin (roles/cloudtasks.queueAdmin), or Cloud Tasks Task Deleter (roles/cloudtasks.taskDeleter).

Delete a task from a queue

You can delete a task if it is scheduled or dispatched. For example, you might need to delete a task that can't be completed successfully, no matter how many times it is retried. You can't delete a task if it has completed successfully or if it has run out of retries after consistently failing. A task is automatically deleted if the maximum task retention limit is reached.

Console

  1. In the Google Cloud console, go to the Cloud Tasks > Queues page.

    Go to Queues

  2. Click the name of the queue for the task that you want to delete.

  3. Select the checkbox for the task that you want to delete.

  4. Click Delete task.

  5. At the prompt, click Delete.

gcloud

Delete a task using the gcloud tasks delete command:

gcloud tasks delete TASK_NAME \
    --queue=QUEUE_ID \
    --location=LOCATION

Replace the following:

  • TASK_NAME: the ID or full resource name of the task that you want to delete
  • QUEUE_ID: the name of the queue that the task belongs to
  • LOCATION: the region in which the queue is deployed—for example, us-central1

REST

To delete a task, use the projects.locations.queues.tasks.delete method.

Before using any of the request data, make the following replacements:

  • QUEUE_ID: the name of the queue that the task belongs to
  • TASK_NAME: the name of the task you want to delete
  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the region in which the queue exists—for example, us-central1

The request body must be empty.

To send your request, expand one of these options:

If successful, the response body is empty.

Delete a batch of tasks from a queue

You can delete a batch of tasks from a queue by using the projects.locations.queues.tasks.batchDelete method to delete a list of task names.

Note the following:

  • All tasks must be deleted from the same queue.

  • There is a limit to how many tasks can be deleted in a single batch. For more information, see Quotas and limits.

  • Batch requests, which aggregate individual operations into a single request, are not atomic because it's possible for some of the operations contained within the batch to fail while others succeed.

  • You can only delete a task if it is scheduled or dispatched. You can't delete a task if it has completed successfully or if it has run out of retries after consistently failing. A task is automatically deleted if the maximum task retention limit is reached.

  • You can also create a batch of tasks. For more information, see Create a batch of tasks.

Before using any of the request data, make the following replacements:

  • TASK_NAME: the name of the tasks to delete with the following format: projects/PROJECT_ID/locations/REGION/queues/QUEUE_ID/tasks/TASK_ID
  • PROJECT_ID: your Google Cloud project ID
  • REGION: the region in which the queue exists—for example, us-central1
  • QUEUE_ID: the name of the queue that the tasks belong to

The request body contains a list of task names.

Request JSON body:

{
  "names": [
    "TASK_NAME"
  ]
}

To send your request, expand one of these options:

If successful, the response body contains an instance of Operation.

{
  "name": "projects/PROJECT_ID/locations/REGION/operations/OPERATION_ID",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.tasks.v2.BatchDeleteTasksMetadata"
  },
  "done": false
}

Purge all tasks from a queue

You can delete all tasks from a queue by purging them. All tasks created before the purge call are permanently deleted. However, purge operations can take up to one minute to take effect and tasks might be dispatched before the purge takes effect.

Console

  1. In the Google Cloud console, go to the Cloud Tasks > Queues page.

    Go to Queues

  2. Click the name of the queue for the tasks that you want to delete.

  3. Click Purge queue.

  4. At the prompt, click Purge.

gcloud

Purge a queue using the gcloud tasks queues purge command:

gcloud tasks queues purge QUEUE_ID \
    --location=LOCATION

Replace the following:

  • QUEUE_ID: the name of the queue that you want to purge
  • LOCATION: the region in which the queue is deployed—for example, us-central1

REST

To purge a queue, use the projects.locations.queues.purge method.

Before using any of the request data, make the following replacements:

  • QUEUE_ID: the name of the queue that you want to purge
  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the region in which the queue is deployed—for example, us-central1

The request body must be empty.

To send your request, expand one of these options:

If successful, the response body contains an instance of Queue:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
  "rateLimits": {
    "maxDispatchesPerSecond": 500,
    "maxBurstSize": 100,
    "maxConcurrentDispatches": 1000
  },
  "retryConfig": {
    "maxAttempts": 100,
    "minBackoff": "0.100s",
    "maxBackoff": "3600s",
    "maxDoublings": 16
  },
  "state": "RUNNING",
  "purgeTime": "2025-03-28T13:06:30.110255Z"
}

Pause or resume queues

You can pause or resume a queue. Pausing a queue stops the execution and delivery of tasks. You can still create tasks and push or append them to the queue, but the tasks aren't processed until the queue is resumed. When you resume a queue, Cloud Tasks begins dispatching backlogged tasks without a defined execution order. If you are resuming high-traffic queues with a large backlog, follow the ramp-up guidance to prevent target overload.

Console

  1. In the Google Cloud console, go to the Cloud Tasks > Queues page.

    Go to Queues

  2. Select the checkbox for the queue that you want to pause or resume.

  3. To pause the queue, click Pause queue, and then click Pause at the prompt.

  4. To resume a paused queue, click Resume queue.

gcloud

  1. Pause a queue using the gcloud tasks queues pause command:

    gcloud tasks queues pause QUEUE_ID \
        --location=LOCATION

    Replace the following:

    • QUEUE_ID: the name of the queue that you want to pause
    • LOCATION: the region in which the queue is deployed—for example, us-central1
  2. Resume a queue using the gcloud tasks queues resume command:

    gcloud tasks queues resume QUEUE_ID \
        --location=LOCATION

REST

  1. To pause a queue, use the projects.locations.queues.pause method.

    Before using any of the request data, make the following replacements:

    • QUEUE_ID: the name of the queue that you want to pause
    • PROJECT_ID: your Google Cloud project ID
    • LOCATION: the region in which the queue is deployed—for example, us-central1

    The request body must be empty.

    To send your request, expand one of these options:

    If successful, the response body contains an instance of Queue:

    {
      "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
      "rateLimits": {
        "maxDispatchesPerSecond": 500,
        "maxBurstSize": 100,
        "maxConcurrentDispatches": 1000
      },
      "retryConfig": {
        "maxAttempts": 100,
        "minBackoff": "0.100s",
        "maxBackoff": "3600s",
        "maxDoublings": 16
      },
      "state": "PAUSED"
    }
    

  2. To resume a queue, use the projects.locations.queues.resume method.

    Before using any of the request data, make the following replacements:

    • QUEUE_ID: the name of the queue that you want to resume
    • PROJECT_ID: your Google Cloud project ID
    • LOCATION: the region in which the queue is deployed—for example, us-central1

    The request body must be empty.

    To send your request, expand one of these options:

    If successful, the response body contains an instance of Queue:

    {
      "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
      "rateLimits": {
        "maxDispatchesPerSecond": 500,
        "maxBurstSize": 100,
        "maxConcurrentDispatches": 1000
      },
      "retryConfig": {
        "maxAttempts": 100,
        "minBackoff": "0.100s",
        "maxBackoff": "3600s",
        "maxDoublings": 16
      },
      "state": "RUNNING"
    }
    

List queues

You can list queues. When listing queues, some rate limit and retry parameter details are returned. Note that the following fields are equivalent:

  • Max rate (Console), MAX_RATE (gcloud), maxDispatchesPerSecond (REST)
  • Max concurrent (Console), MAX_NUM_OF_TASKS (gcloud), maxConcurrentDispatches (REST)

Console

  1. In the Google Cloud console, go to the Cloud Tasks > Queues page.

    Go to Queues

    All queues in your Google Cloud project are listed.

  2. For more details, click the name of a queue, and then click the Configuration tab.

    Rate limit and retry parameter details are displayed.

gcloud

List queues using the gcloud tasks queues list command:

gcloud tasks queues list \
    --location=LOCATION

Replace LOCATION with the region in which the queue is deployed—for example, us-central1. If a location is not specified, the location of your Google Cloud project's App Engine app is used if it exists; otherwise, you must specify a location.

The output should be similar to the following:

QUEUE_NAME: my-queue
STATE: PAUSED
MAX_NUM_OF_TASKS: 1000
MAX_RATE (/sec): 500.0
MAX_ATTEMPTS: 100
...

REST

To list queues, use the projects.locations.queues.list method.

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Google Cloud project ID.
  • LOCATION: the region in which the queues are created—for example, us-central1.

To send your request, expand one of these options:

If successful, the response body contains instances of Queue resources and the response should be similar to the following:

{
  "queues": [
    {
      "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID",
      "rateLimits": {
        "maxDispatchesPerSecond": 500,
        "maxBurstSize": 100,
        "maxConcurrentDispatches": 1000
      },
      "retryConfig": {
        "maxAttempts": 100,
        "minBackoff": "0.100s",
        "maxBackoff": "3600s",
        "maxDoublings": 16
      },
      "state": "PAUSED",
      "purgeTime": "2025-03-28T13:37:32.292552Z"
    },
    ...
  ],
  "nextPageToken": "CjQKCHppcHBlcjIAEgwI9-GExAYQ_oDc1AMaGioLeWlrZXMtYWdhaW4yC3VzLWNlbnRyYWwx"
}

Delete queues

You can delete any queue when you no longer need it, except the App Engine default queue. After you delete a queue, you must wait 3 days before recreating it with the same name. This waiting period applies to queues deleted through any interface, including the Google Cloud console, the gcloud CLI, the REST or RPC API, or Terraform. It prevents unexpected behavior in tasks that are executing at the time of deletion and avoids internal process failures during the delete and recreate cycle.

During this tombstone window of up to 3 days, a queue creation request might appear to succeed without recreating the queue. To confirm that a queue with the same name was recreated, retrieve the queue using the gcloud tasks queues describe command or the projects.locations.queues.get method. A successful (200 OK) response confirms that the queue was recreated.

To clear tasks, modify queue configurations, or manage queues in CI/CD pipelines without losing the queue or triggering the 3-day waiting period, use the following alternatives instead of deleting and recreating a queue:

To delete a queue, use the Google Cloud console, the gcloud CLI, or the Cloud Tasks API:

Console

  1. In the Google Cloud console, go to the Cloud Tasks > Queues page.

    Go to Queues

  2. Select the checkbox for the queue that you want to delete.

  3. Click Delete queue.

  4. At the prompt, enter the queue name, and then click Confirm.

gcloud

Delete a queue using the gcloud tasks queues delete command:

gcloud tasks queues delete QUEUE_ID \
    --location=LOCATION

Replace the following:

  • QUEUE_ID: the ID or fully qualified identifier of the queue that you want to delete
  • LOCATION: the region in which the queue is deployed—for example, us-central1

The gcloud CLI prompts for confirmation before deleting the queue unless you pass the --quiet flag.

REST

To delete a queue, use the projects.locations.queues.delete method.

Before using any of the request data, make the following replacements:

  • QUEUE_ID: the name of the queue that you want to delete
  • PROJECT_ID: your Google Cloud project ID
  • LOCATION: the region in which the queue is deployed—for example, us-central1

The request body must be empty.

To send your request, expand one of these options:

If successful, the response body is empty.

What's next