Cloud Tasks is a managed service that lets you hand off units of work to be done later, reliably, and at a speed you control.

The problem it solves

Imagine a customer presses a button to place an order. Your website must save the order, send a confirmation email, update a stock count, tell a shipping partner, and resize the product photo for a receipt. If the website does all of that before replying, the customer waits, and if any step fails, the whole request may fail. A better design replies quickly after the essential step and does the rest in the background. Background work is called asynchronous processing, meaning the caller does not wait for it to finish.

Doing background work well is harder than it sounds. You need somewhere to store the pending work so it is not lost if a server restarts. You need to deliver it to a worker, retry when the worker fails, and avoid flooding a fragile partner system with thousands of calls at once. Building all of that yourself is slow and error-prone. Cloud Tasks provides it as a ready-made service.

What the service actually does

You create a queue, which is a named holding area for jobs. Your code adds tasks to the queue. A task contains the address of a handler and any data the handler needs. Cloud Tasks then sends each task to its handler, which is simply a web endpoint you own, such as a Cloud Run service or a Cloud Run function. If the handler replies with a success code, the task is finished and removed. If it fails or does not reply in time, Cloud Tasks waits a while and tries again, according to rules you set.

The service is fully managed, so there are no queue servers to run, patch or scale. You pay for what you use, and you control the pace at which tasks are sent, which protects both your own services and any outside systems they call.

Cloud Tasks works with several neighbours, and confusing them is the most common beginner mistake.

Cloud Tasks versus Pub/Sub, in one sentence

Use Cloud Tasks when your code knows exactly which handler must do a piece of work and you want control over timing, speed and retries. Use Pub/Sub when you want to announce that something happened and let any number of independent listeners react without the sender knowing about them.

Cloud Tasks versus Cloud Scheduler

Cloud Scheduler fires on a clock: every night at two, every five minutes. Cloud Tasks handles work created by events: this particular customer, this particular file, in fifteen minutes. A common pairing is a scheduler job that wakes at night and creates thousands of tasks, one for each item that needs processing.

flowchart LR
  P["Your application"] -->|"Create task"| Q["Cloud Tasks queue"]
  Q -->|"Dispatch at controlled rate"| H["Handler on Cloud Run or similar"]
  H -->|"Success code"| Q
  Q --> L["Cloud Logging and Monitoring"]
  S["Cloud Scheduler"] -.->|"Optional trigger"| P
  W["Workflows"] -.->|"Optional step"| Q
        

A small set of words unlocks the whole service.

Knowing exactly what lives in a queue and in a task removes most early confusion.

What a queue holds

A queue lives in one project and one location, a geographic region. Its location is chosen when it is created and cannot be changed later, so pick the region near your handlers. A queue has a name, a state (running, paused or disabled), a rate limit policy, a retry policy, and optional settings for logging. Names can be reused only after a waiting period once a queue is deleted, so choose names with care.

What a task holds

Four roles take part in every task: the producer, the queue, the dispatcher and the handler.

Although Cloud Tasks is fully managed, picturing its parts helps explain its behaviour. Each part has a clear job.

flowchart LR
  subgraph You["Your code"]
    PR["Producer"]
    HD["Handler"]
  end
  subgraph GC["Cloud Tasks"]
    QU["Queue storage"]
    DP["Dispatcher with rate limits and retries"]
  end
  PR -->|"Create task"| QU
  QU --> DP
  DP -->|"HTTP request"| HD
  HD -->|"Response code"| DP
  DP --> OB["Logs and metrics"]
        

The handler is a normal web service

One of the nicest things about Cloud Tasks is that handlers need no special software. A handler is simply a web endpoint that accepts a request and replies with a status. This means you can write it in any language, test it with ordinary tools, and host it wherever it can receive web requests, most commonly on Cloud Run or as a Cloud Run function. It also means that anyone who can call that endpoint could, in principle, send it work, which is why authentication matters, as we will see.

Follow a single task from creation to completion, including what happens when things go wrong.

Let us trace an example. A customer places an order, and your website wants to send a confirmation email in the background. Here is the life of that email task.

sequenceDiagram
  participant W as Website
  participant Q as Cloud Tasks queue
  participant H as Email handler
  W->>Q: Create task with order number
  Q-->>W: Task stored
  W-->>W: Reply to customer immediately
  Q->>H: Dispatch attempt 1
  H-->>Q: Error response
  Note over Q: Wait with backoff
  Q->>H: Dispatch attempt 2
  H-->>Q: Success response
  Q->>Q: Remove task
        

What the handler learns from headers

Each request carries information that helps the handler behave well. Headers tell it the queue name, the task name, how many times the task has been retried, how many times it has been executed, and when it was scheduled. A handler can use these to log context, to give up on tasks that have been tried too often, and to detect that a request came from Cloud Tasks and not from a stranger. Check the current documentation for the exact header names.

Cloud Tasks can deliver to two kinds of targets, and the success rule is the same for both.

HTTP targets

HTTP target tasks go to any web endpoint that Cloud Tasks can reach, such as a Cloud Run service, a Cloud Run function, a service on a virtual machine, or even an endpoint outside Google Cloud. You specify the address and the method. This is the most flexible and most common option today.

App Engine targets

Tasks can also be sent to a handler inside an App Engine application, with routing based on the service and version. This option is tied to App Engine, and it offers features such as routing to a particular version and longer deadlines on some scaling types. If you do not already use App Engine, you will almost always choose HTTP targets.

What counts as success

The rule is simple. A handler that replies with a success status, any code in the two hundreds, tells Cloud Tasks that the work is done. Any other reply, such as a client error, a server error or a timeout, is treated as a failure and the task is retried. This means the handler controls its own fate through the status it returns.

Cloud Tasks promises that your task will be delivered at least once, which has a big consequence for how you write handlers.

At least once, not exactly once

The service is designed to deliver every task at least once. In rare cases a task may be delivered more than once, for example when a handler does the work but the success reply is lost on the network, or when a slow handler times out and the task is retried while the first attempt is still running. From the dispatcher’s point of view, no success was seen, so it tries again. This is a deliberate design choice: it is far better to deliver twice than to lose the work.

Idempotent handlers: the golden rule

A handler is idempotent if running it twice with the same task has the same effect as running it once. Sending the same welcome email twice is annoying, and charging a customer twice is a serious problem. Writing idempotent handlers is the single most important habit in background processing.

About ordering

Cloud Tasks does not promise that tasks run in the exact order they were added. Tasks are dispatched roughly in order of their due time, but retries, parallel dispatch and scheduling mean the order can vary. If your work depends on strict order, such as applying edits to one document in sequence, do not rely on queue order. Instead, include a sequence number in the task, have the handler apply changes only in the right order, or use a service that offers ordering guarantees for that case.

flowchart TD
  T["Task arrives at handler"] --> C{"Already processed this business key?"}
  C -->|Yes| S["Skip the work and return success"]
  C -->|No| W["Do the work"]
  W --> R["Record completion with the key"]
  R --> OK["Return success"]
        

The queue is a pressure valve that protects everything downstream.

Why speed control matters

Imagine ten thousand tasks arrive in one minute, each needing to call a partner system that can handle only fifty requests per second. If all ten thousand were sent at once, the partner would fail, your handlers would fail, retries would pile up, and the failure would spread. Rate limits turn a dangerous spike into a smooth, safe flow.

The three dials

flowchart LR
  A["Tasks waiting in queue"] --> B["Token bucket refills at the set rate"]
  B --> C{"Token available and concurrency below limit?"}
  C -->|Yes| D["Dispatch task to handler"]
  C -->|No| E["Task waits in queue"]
  E --> C
        

Choosing the numbers

Begin with the capacity of your weakest link. If a partner allows one hundred requests per second, set the rate lower, perhaps eighty, to leave room for other users of the same partner. If your database allows twenty connections for background work, cap concurrency near that. Then watch the backlog and latency and adjust gradually. A queue with a very high rate limit is not a bad thing in itself, but it gives no protection to a fragile dependency.

Failure is normal in distributed systems, so retrying wisely is a core feature, not an afterthought.

Why tasks fail

A handler may fail for many reasons: a database is restarting, a partner system is overloaded, the network drops a packet, a deployment is in progress, or the task itself contains bad data. Most of these problems are temporary. If you wait a little and try again, the work succeeds. Retrying is therefore the right first response to a failure.

Backoff: waiting longer each time

If a system is struggling, hammering it with instant retries makes things worse. Exponential backoff means the wait doubles after each failure, up to a ceiling. A task might wait a fraction of a second, then a second, then two, then four, and so on, until the maximum wait is reached. This gives a failing service room to recover and prevents a retry storm.

The retry settings on a queue

flowchart TD
  A["Dispatch attempt"] --> B{"Handler returned success?"}
  B -->|Yes| C["Task finished and removed"]
  B -->|No| D{"Attempts or time limit reached?"}
  D -->|Yes| E["Task dropped"]
  D -->|No| F["Wait with growing backoff"]
  F --> A
        

Matching retry rules to the kind of work

Tasks can wait for a chosen moment, and every attempt has a time limit.

Delaying a task

Each task can carry a schedule time, a moment before which it must not run. This is wonderful for delayed actions: send a reminder in thirty minutes, check on an order tomorrow, retry a partner call after an hour. The delay is limited to a maximum number of days into the future, documented as about thirty days at the time of writing, so very long waits need a different design.

Dispatch deadline: how long a handler may take

Every attempt has a deadline, the time Cloud Tasks will wait for the handler’s reply. If the handler does not answer within the deadline, the attempt is counted as failed. For HTTP targets the deadline has a default and a maximum, documented in minutes at the time of writing, and it can be set per task within those limits. App Engine targets have their own limits depending on how the application scales. Always confirm the current numbers in the documentation.

Long-running work

If a job takes longer than the maximum deadline, do not simply increase the deadline and hope. Split the work into smaller tasks, or have the handler accept the task, start the work elsewhere, and reply right away. Long jobs are better handled by a task that triggers a dedicated job service and then records its progress.

A task name can act as a safety latch that refuses accidental duplicates at creation time.

Named and unnamed tasks

When you create a task you may give it a name, or leave it out and let the service make one. A name that you choose becomes a unique identity within the queue. If your code tries to create another task with the same name while the first still exists, the service refuses with an already-exists answer. This protects you when a producer runs twice, for example after its own retry.

How to choose a name

Pick a name from a stable business key, such as an order number combined with the kind of work. For example, “confirm-email for order 8841” always produces the same name for the same job, so duplicates are refused. Avoid names that include the current time or a random value, because those are always unique and give no protection.

Limits of name-based protection

Deduplication by name works only for a limited time. Once a task has been completed or deleted, its name cannot be reused for a period of time, documented as roughly an hour at the time of writing, and after that the name is free again. Therefore name-based protection does not replace idempotent handlers. It is an extra safety net at creation time, while the handler’s own check is the safety net at execution time.

A queue has controls that let you stop the flow, clear the backlog, or switch it off entirely.

stateDiagram-v2
  [*] --> Running
  Running --> Paused: Pause
  Paused --> Running: Resume
  Running --> Disabled: Disable
  Disabled --> Running: Enable again
  Running --> Running: Purge removes all tasks
  Disabled --> [*]: Delete queue
        

When to pause

Two questions must be answered: who may add tasks, and how does your handler know a request really came from Cloud Tasks?

Who may do what with queues

Access is managed through Identity and Access Management using predefined roles. A good design gives each identity only the role it needs.

Proving who is calling the handler

Your handler is a web endpoint, and anyone who learns its address might call it. To prevent that, Cloud Tasks can attach a signed token to every request, created for a service account that you choose. The handler, or the platform in front of it, checks the token before doing anything. For handlers on Cloud Run and Cloud Run functions, you generally use an identity token and grant that service account permission to invoke the service. For Google APIs, an access token is used instead.

What you put in a task and where the handler lives both affect your security.

Private and public handlers

Handlers that are reachable from the internet are simplest to use, but you can lock them down by requiring authentication, as discussed. For handlers that live inside a private network, Cloud Tasks offers options to reach them without exposing them publicly. Availability and setup details depend on the current features, so consult the documentation before designing around them. Many teams keep handlers private to the platform, accepting only authenticated calls.

What belongs inside a task

Why identifiers beat copies of data

Tasks may sit in a queue for minutes, hours or days, may be retried, and show up in logs and troubleshooting tools. If a task carries a full copy of a customer record, that copy may be stale by the time it runs and may also appear in places you did not intend. A task that carries only an identifier lets the handler fetch the freshest data and keeps sensitive content in one controlled place.

A background queue is out of sight, so it must be well lit.

Because background work happens away from the user, problems can grow quietly for hours. Good observability tells you early. Three sources matter: logs of each attempt, metrics about the queue, and your own handler records.

Logs of task attempts

Cloud Tasks can write a log record for task attempts, showing the queue, the task, the attempt number, the response code and the timing. Logging has a sampling setting that controls what share of attempts is recorded, so you can balance detail against volume and cost. Turn it on for important queues, and make sure your handler also logs its own decisions with the task name.

Metrics that matter

Alerts worth having

flowchart LR
  Q["Queue activity"] --> M["Queue metrics"]
  Q --> L["Attempt logs"]
  H["Handler logs"] --> L
  M --> D["Dashboard"]
  M --> A["Alerting policies"]
  L --> A
  A --> O["On-call engineer"]
        

Some tasks can never succeed, and a good design decides what happens to them.

What is a poison task?

A poison task is one that fails every time, no matter how often it is retried. Perhaps it refers to a record that was deleted, contains malformed data, or triggers a bug in the handler. Left alone, it consumes retries, adds noise to logs, and may hide real problems. After the maximum attempts, the service drops the task, which means the failure could pass unnoticed.

Dead letters: the problem shelf

A dead-letter store is a place where failed work is kept for human review. Cloud Tasks does not provide a built-in dead-letter queue at the time of writing, so check the current documentation, and design your own pattern when you need one.

flowchart TD
  T["Task attempt arrives"] --> W{"Work succeeded?"}
  W -->|Yes| OK["Return success"]
  W -->|No| P{"Permanent error or retry limit reached?"}
  P -->|No| RT["Return error and let queue retry"]
  P -->|Yes| DL["Save task details to dead-letter store and raise alert"]
  DL --> OK2["Return success to stop retries"]
        

Choosing the right tool saves months of pain.

flowchart TD
  Q1{"Do you know exactly which handler must do the work?"}
  Q1 -->|Yes| Q2{"Need control over speed, retries or delay per item?"}
  Q1 -->|No| PS["Use Pub/Sub for event announcements"]
  Q2 -->|Yes| CT["Use Cloud Tasks"]
  Q2 -->|No| Q3{"Is it a repeating schedule?"}
  Q3 -->|Yes| CS["Use Cloud Scheduler"]
  Q3 -->|No| Q4{"Many steps with decisions and waiting?"}
  Q4 -->|Yes| WF["Use Workflows"]
  Q4 -->|No| CT
        

They often work together

Real systems combine these tools. A scheduler job wakes at night and creates tasks for each customer. A workflow handles a complex order, using tasks for the throttled partner calls. A Pub/Sub event announces that an order was placed, and one subscriber responds by creating tasks. Treat them as parts of a toolkit.

A calm, ordered path from an empty project to a working queue.

Setup is simple when done in the right order. Think of it as setting up a new mail room in an office: you choose the room, label the pigeonholes, decide who may post and who may collect, and test a letter before relying on it.

Good background processing comes from a handful of repeatable habits.

flowchart LR
  S["Nightly scheduler job"] --> C["Coordinator handler"]
  C -->|"Create one task per customer"| Q["Throttled queue"]
  Q -->|"Rate limited"| H["Worker handler"]
  H --> P["Partner system with fixed quota"]
  H --> D["Database record of completed keys"]
        

These habits quietly cause duplicates, backlogs and outages.

A checklist in plain words that any team can adopt.

Common mistakes beginners make

The same service supports very different businesses. These scenarios show how.

flowchart LR
  O["Order placed"] --> Q1["Email queue"]
  O --> Q2["Stock queue"]
  O --> Q3["Warehouse queue"]
  Q1 --> H1["Email handler"]
  Q2 --> H2["Stock handler"]
  Q3 --> H3["Warehouse handler"]
        

The service is inexpensive for most teams, but design choices affect the bill and the limits you meet.

How charges usually work

Pricing is based on the number of billable operations, such as creating tasks and dispatching attempts, usually with a monthly free allowance and a price per million operations beyond it. Retries count as additional attempts, so a flapping handler raises both load and cost. Your handlers, logs, databases and network also cost money. Always check the current pricing page for exact figures, because they change.

Quotas and limits

Cloud Tasks has limits on things such as the number of queues, the size of a task, how far ahead a task may be scheduled, and the rates at which you can create tasks and send them. Many limits are generous for normal use, and some can be raised on request. Review the current quota page before big launches, design producers to retry creation calls with short waits when they are throttled, and spread very large bursts of task creation over a little time.

Scaling to large volumes

An honest comparison always includes the limits.

How the options compare

When something looks wrong, follow the task from the producer to the handler, one link at a time.

flowchart TD
  A["Tasks not completing as expected"] --> B{"Are tasks being created successfully?"}
  B -->|No| C["Check enqueuer permission, act-as permission, queue name and region"]
  B -->|Yes| D{"Is the queue running and not paused?"}
  D -->|No| E["Resume the queue"]
  D -->|Yes| F{"Are attempts reaching the handler?"}
  F -->|No| G["Check handler address, invoker permission and authentication"]
  F -->|Yes| H{"Is the handler returning success in time?"}
  H -->|No| I["Fix errors, shorten work, align timeouts and deadlines"]
  H -->|Yes| J{"Is backlog still growing?"}
  J -->|Yes| K["Raise limits carefully or scale the handler and dependencies"]
  J -->|No| L["Read attempt logs for the exact reason"]
        

Symptom: task creation fails

Check that the producer has the enqueuer role, that it may act as the service account named in the task, that the queue name and region are correct, and that the task is within size and schedule limits. Permission and name errors are the most common causes.

Symptom: tasks sit in the queue and nothing runs

First check whether the queue is paused or disabled. Then check the rate limits: a very low dispatch rate or concurrency limit makes the queue crawl. Finally check whether tasks are scheduled for a future time.

Symptom: every attempt fails with an authorisation error

The dispatch service account may lack permission to invoke the handler, or the handler may expect a different kind of token or audience. Confirm the identity, the invoker permission and the target address used in the token.

Symptom: duplicates appear

Timeouts are the usual cause: the handler was too slow, the attempt was counted as failed, and a retry started. Shorten the work, align timeouts, and make the handler idempotent.

Symptom: backlog keeps growing

Tasks arrive faster than they are completed. Check handler errors, handler scaling, dependency health, and queue limits. Raise limits only if the handler and dependencies can cope, otherwise you simply move the pain.

Preparation turns a frightening pile-up into a managed event.

Sooner or later a dependency fails, a bad release goes out, or a rush of tasks arrives. The queue starts to fill, retries multiply, and alerts begin to fire. A short written playbook helps the team act calmly.

sequenceDiagram
  participant M as Monitoring
  participant T as On-call team
  participant Q as Queue
  participant D as Dependency
  M->>T: Alert on growing backlog
  T->>T: Find cause in logs and metrics
  T->>Q: Pause queue to stop retries
  T->>D: Repair or wait for recovery
  T->>Q: Resume with low limits
  Q-->>M: Backlog shrinks steadily
  T->>Q: Raise limits in steps
  T->>T: Review and improve playbook
        

Introduce background processing carefully, prove that it works, and grow it in stages.

The riskiest moment of any queue project is the first launch, because mistakes show up as lost, delayed or duplicated work. A calm testing and rollout plan removes most of that risk.

What to test before launch

A gentle rollout plan

flowchart LR
  ST["Staging tests"] --> L1["One low-risk flow in production"]
  L1 --> AN["Study metrics and costs"]
  AN --> EX["Expand flow by flow"]
  EX --> OP["Operate, review and retune"]
  OP -.->|"Learn and adjust"| AN
        

A maturity path

A queue is a named holding area with rules for speed and retries. A task is one unit of work inside the queue, with the handler address, data and optional timing.

No. A successful create call only means the task was stored safely. The work happens later, and the result is not returned to the producer.

Yes. Delivery is at least once, so a task may be delivered more than once in rare cases, especially after timeouts. Make handlers idempotent.

Not strictly. Retries and parallel dispatch can change the order. If order matters, include sequence information and let the handler ignore stale updates.

A success status in the two hundreds. Any other reply, or no reply within the deadline, is treated as a failure and the task is retried.

They cap the speed and concurrency of dispatch, protecting handlers and outside systems from floods and turning spikes into a steady flow.

Failed tasks wait with a growing delay and are tried again until they succeed or reach the limit of attempts or total retry time that you set on the queue.

Not built in at the time of writing, so check the current documentation. Teams usually build their own pattern by recording permanently failing tasks and alerting.

Cloud Tasks sends a job to a specific handler chosen by the sender, with control over speed, delay and retries. Pub/Sub announces events to any number of independent subscribers.

Require authentication, use a dedicated service account for dispatch with permission to invoke only that handler, and never rely on the secrecy of the address.

Yes, with a schedule time, up to a limited number of days ahead. For longer delays, store the intent and create the task closer to the time.

For most teams the cost is modest, often with a free monthly allowance and a price per million operations beyond it. Handler compute and logging may cost more. Check the current pricing page.

Cloud Tasks is the reliable ticket rail of your cloud applications. Producers add small tasks to named queues, and the managed dispatcher delivers each task to a handler you control, at a speed you set, retrying with growing waits when something fails. Tasks can be delayed with a schedule time, protected against duplicate creation with names, and observed through logs and metrics. Delivery is at least once and order is not guaranteed, so handlers must be idempotent and must carry out their own checks. Good design separates queues by dependency, authenticates every handler, passes identifiers instead of secrets, records permanently failing tasks, and watches backlog and age. With these habits, background work becomes dependable, customer requests stay fast, and fragile partners stay safe.