Create Cloud Tasks queues

This page describes how to create Cloud Tasks queues. When tasks are added to a queue, the queue dispatches them and makes sure they are reliably processed by a service, also known as a worker.

Note the following:

Queue names consist of three parts: a project ID, a location, and a queue ID. You must have a Google Cloud project which provides the project ID.
If you are using App Engine target tasks, you must also have an App Engine application which is located in a specific region and which is where your queue and your handlers run. Note the region when you add the app.

Note: Two locations, called europe-west and us-central in App Engine commands, are called, respectively, europe-west1 and us-central1 in Cloud Tasks commands.
Using HTTP Target tasks doesn't require an App Engine app. You select a Google Cloud location when you create your queue.

Create a queue

You can create a queue in the following ways:

In the Google Cloud console
By using the Google Cloud CLI in either your terminal or Cloud Shell
By sending a direct request to the Cloud Tasks API

Console

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

Go to Queues
Click Create queue.
Enter a Queue name—for example, my-queue.
In the Region list, select a supported location where the queue will run—for example, asia-south1.

If your organization restricts resource location and you want to create your queue in either us-central1 or us-central2, the organization policy must allow queue creation in both us-central1 and us-central2 (even if you only need a queue in one of those regions).
Optionally, you can further configure your queue.
Click Create.

gcloud

Use the gcloud tasks queues create command to create your queue:

  gcloud tasks queues create QUEUE_ID \
      --location=LOCATION

Replace the following:

QUEUE_ID: the identifier you assign to your queue—for example, my-queue.
LOCATION: a supported region where the queue will run—for example, asia-south1.

If your organization restricts resource location and you want to create your queue in either us-central1 or us-central2, the organization policy must allow queue creation in both us-central1 and us-central2 (even if you only need a queue in one of those regions).

Other flags for the gcloud CLI command let you configure rate limits, retry options, queue types, and more.

REST API

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

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

PROJECT_ID: your Google Cloud project ID.
LOCATION: a supported region where the queue will run—for example, asia-south1.
If your organization restricts resource location and you want to create your queue in either us-central1 or us-central2, the organization policy must allow queue creation in both us-central1 and us-central2 (even if you only need a queue in one of those regions).
QUEUE_ID: the identifier you assign to your queue—for example, my-queue.

Other configurable properties for the Queue resource include rate limits, retry options, queue types, and more.

Request JSON body:

{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"
}

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login , or by using Cloud Shell, which automatically logs you into the gcloud CLI . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

cat > request.json << 'EOF'
{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"
}
EOF

Then execute the following command to send your REST request:

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues"

PowerShell (Windows)

Note: The following command assumes that you have logged in to the gcloud CLI with your user account by running gcloud init or gcloud auth login . You can check the currently active account by running gcloud auth list.

Save the request body in a file named request.json. Run the following command in the terminal to create or overwrite this file in the current directory:

@'
{
  "name": "projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"
}
'@  | Out-File -FilePath request.json -Encoding utf8

Then execute the following command to send your REST request:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues" | Select-Object -Expand Content

APIs Explorer (browser)

Copy the request body and open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Paste the request body in this tool, complete any other required fields, and click Execute.

If successful, the response body contains a newly created 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"
}

It can take a few minutes for a newly created queue to be available.

Describe your queue

You can confirm that your queue was created successfully in the following ways:

In the Google Cloud console
By using the gcloud CLI in either your terminal or Cloud Shell
By sending a direct request to the Cloud Tasks API

Console

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

Go to Queues

A green checkmark should indicate that your queue is running.
For more details, click the name of the queue, and then click the Configuration tab.

gcloud

Use the gcloud tasks queues describe command to verify that your queue was created successfully:

gcloud tasks queues describe QUEUE_ID \
    --location=LOCATION

Replace the following:

QUEUE_ID: the queue ID (its short name)
LOCATION: the location of the queue

The output should be similar to the following:

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

REST API

To retrieve a queue, use the projects.locations.queues.get 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 queue is deployed—for example, us-central1.
QUEUE_ID: the short ID of the queue—for example, my-queue.

To send your request, expand one of these options:

curl (Linux, macOS, or Cloud Shell)

Execute the following command:

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID"

PowerShell (Windows)

Execute the following command:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://cloudtasks.googleapis.com/v2/projects/PROJECT_ID/locations/LOCATION/queues/QUEUE_ID" | Select-Object -Expand Content

APIs Explorer (browser)

Open the method reference page. The APIs Explorer panel opens on the right side of the page. You can interact with this tool to send requests. Complete any required fields and click Execute.

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"
}

Troubleshoot creating a queue

If you don't see the expected output, you can try the following:

Wait at least one minute for the queue to initialize.
Make sure a queue with the same ID does not already exist. You can view the queues in your project by using the gcloud tasks queues list command:
```
gcloud tasks queues list \
    --location=LOCATION
```
To search multiple locations you need to make multiple requests.
Check if you've reached your queue quota:
1. In the Google Cloud console, go to the API/Service Details page for the Cloud Tasks API .
  
  Go to API/Service Details
2. Click the Quotas & System limits tab.
3. To increase a quota, in the row for the quota, click the ellipsis icon > Edit quota.
  
  For more information, see Request a higher quota value.
Re-run the commands to create your queue and ensure that each step is completed correctly.

Create Cloud Tasks queues

Create a queue

Console

gcloud

REST API

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Describe your queue

Console

gcloud

REST API

curl (Linux, macOS, or Cloud Shell)

PowerShell (Windows)

APIs Explorer (browser)

Troubleshoot creating a queue

What's next