Async task queues for heavy workloads
Fan out long-running, GPU-heavy functions across the cloud with a single function call. Enqueue from an API or directly in Python, run thousands of tasks in parallel, and retrieve results when they’re ready. Failed tasks retry automatically.
@task_queue(gpu="RTX4090", retries=3,
autoscaler=QueueDepthAutoscaler(max_containers=8))Run thousands of tasks in parallel
Offload heavy functions to a managed queue, fan them out across the cloud, and retrieve results whenever you need them. Beam starts the workers and scales them with the queue.
Fan out in parallel
Enqueue thousands of tasks with a single call. Beam returns a Task ID instantly and spins up workers to process the queue concurrently, then scales back to zero when the work is done.
Built-in retries
If a task fails, whether from an out-of-memory error or an application exception, it's retried three times before moving to a failed state, so a transient failure doesn't lose the work.
GPUs
Set the GPU, CPU, and memory in the function decorator. Beam provisions the machines, so there are no clusters to set up.
Save and return outputs
Wrap results, artifacts, or generated files in Beam's Output class to upload them to storage and get a URL you can retrieve later.
Webhooks & polling
Receive results via a callback_url webhook the moment a task completes, or poll the /task API for outputs and live queue stats on your own schedule.
Enqueue from anywhere
Trigger tasks over a deployed API, or enqueue them directly in Python with .put() when you don't want to expose an endpoint.
How task queues work
Define a task queue
Add the @task_queue decorator to any Python function and configure CPU, memory, GPU, and your image in the same place, in Python.
Enqueue tasks
POST to the deployed API or call .put() in Python. Requests return a Task ID immediately and Beam fans the work out across workers so nothing blocks.
Retrieve your results
Get a webhook fired to your callback_url the moment a task finishes, or poll the /task API for outputs and live queue stats.
from beam import task_queue, Image
# 1. Decorate any function as a task queue
@task_queue(
cpu=1.0,
memory=128,
gpu="T4",
image=Image(python_packages=["torch"]),
)
def multiply(x):
return {"result": x * 2}
# 2. Enqueue a task — returns instantly
multiply.put(x=10)
# => Enqueued task: f0d205da-e74b-47ba...
# 3. Retrieve the result via webhook or the /task APIFrequently asked questions
What is a task queue?
A task queue lets you deploy resource-intensive functions on Beam. Instead of processing tasks immediately, you add them to a queue and process them later, one at a time or concurrently, without blocking the caller.
When should I use a task queue instead of an endpoint?
Endpoints are RESTful APIs designed for synchronous tasks that complete in 180 seconds or less. For longer-running or GPU-heavy jobs, use an async task_queue so requests return immediately and the work runs in the background.
Can I run tasks in parallel?
Yes. Enqueue as many tasks as you need and Beam fans them out across workers to run concurrently, autoscaling to handle the load and scaling back to zero when the queue is empty. You can also process tasks sequentially when ordering matters.
Do I have to manage any infrastructure?
No. Define a function, attach the GPU and resources you need, and Beam provisions, scales, and tears down the workers.
How do I create one?
Add the @task_queue decorator to any function and configure cpu, memory, gpu, and your image. You can then enqueue tasks over the deployed API or directly in Python with .put().
How do I get the result of a task?
Because task queues are async, the API returns a Task ID. Retrieve results either by adding a callback_url so Beam fires a webhook when the task completes, or by polling the /task API, where your saved Outputs appear in the outputs list.
What happens if a task fails?
Task Queues include a built-in retry system. If a task fails for any reason, such as an out-of-memory error or an application exception, it's retried three times before automatically moving to a failed state.
Can I queue tasks without exposing an endpoint?
Yes. Call the .put() method directly in Python to insert tasks into the queue from scripts or other services without deploying an API.
Give your agents their own machines
Sign up, install the CLI, and launch a sandbox, VM, or GPU from your terminal or your coding agent.