Querying Task Status

You can check the status of any task by querying the task API:

https://api.beam.cloud/v2/task/{TASK_ID}/

The workspace gateway also provides GET /api/v1/task/{workspaceId}/{taskId} with a Beam bearer token. Obtain the workspace ID from /api/v1/workspace/current. The workspace and api.beam.cloud/v2 responses are different representations; do not assume their fields are interchangeable. See workspace REST.

Getting the Task ID

• Task queues return the ID when you submit a task, as {"task_id": "edbcf7ff-e8ce-4199-8661-8e15ed880481"}. See Running Tasks.
• Endpoints and ASGI apps return it in the X-Task-Id response header.
• beam task list shows the IDs of recent tasks, and inside your handler the ID is available as context.task_id.

Task Statuses

Your payload will return the status of the task. These are the possible statuses for a task:

Status	Description
PENDING	The task is enqueued and has not started yet.
RUNNING	The task is running.
COMPLETE	The task completed without any errors.
RETRY	The task is being retried. Defaults to 3, unless retries is provided on a supported decorator.
CANCELLED	The task was cancelled by the client.
TIMEOUT	The task timed out, based on the timeout provided in the function decorator.
EXPIRED	The task remained in the queue and was never picked up by a worker. Pending expiry is controlled separately from execution timeout; see timeouts and retries.
ERROR	The task did not complete successfully.

Request

curl -X GET \
  'https://api.beam.cloud/v2/task/{TASK_ID}/' \
  -H 'Authorization: Bearer [YOUR_AUTH_TOKEN]' \
  -H 'Content-Type: application/json'

Response

The response to /task returns the following data:

Field	Type	Description
id	string	The unique identifier of the task.
started_at	string	The timestamp when the task started, in ISO 8601 format. Null if the task hasn’t started yet.
ended_at	string	The timestamp when the task ended, in ISO 8601 format. Null if the task is still running or hasn’t started.
status	string	The current status of the task (e.g., COMPLETE, RUNNING, etc.).
container_id	string	The identifier of the container running the task.
updated_at	string	The timestamp when the task was last updated, in ISO 8601 format.
created_at	string	The timestamp when the task was created, in ISO 8601 format.
outputs	array	An array containing the outputs of the task.
stats	object	An object containing statistics about the task’s execution environment.
stats.active_containers	integer	The number of active containers for the task.
stats.queue_depth	integer	The depth of the queue for the deployment.
stub	object	An object containing detailed information about the task’s configuration and deployment.
stub.id	string	The identifier of the deployment stub.
stub.name	string	The name of the deployment stub.
stub.type	string	The type of the deployment stub.
stub.config	string	The configuration details of the deployment stub, as a JSON-encoded string.
stub.config_version	integer	The version number of the deployment stub configuration.
stub.created_at	string	The timestamp when the deployment stub was created, in ISO 8601 format.
stub.updated_at	string	The timestamp when the deployment stub was last updated, in ISO 8601 format.
deployment	object	The deployment the task ran on.
deployment.name	string	The deployment name. Null for tasks from beam serve.
deployment.version	string	The deployment version. Null for tasks from beam serve.

Here’s what the response payload looks like as JSON:

{
  "id": "c5f01c46-4eb3-4021-9d5f-eae9a08c4aad",
  "started_at": "2025-05-22T22:49:03.839612Z",
  "ended_at": "2025-05-22T22:49:03.913964Z",
  "status": "COMPLETE",
  "container_id": "taskqueue-da2e6878-e202-40d4-9b7a-21706f3a2b13-c23f1166",
  "updated_at": "2025-05-22T22:49:03.915891Z",
  "created_at": "2025-05-22T22:49:03.832363Z",
  "outputs": [],
  "stats": {
    "active_containers": 1,
    "queue_depth": 0
  },
  "stub": {
    "id": "da2e6878-e202-40d4-9b7a-21706f3a2b13",
    "name": "taskqueue/serve/app:handler",
    "type": "taskqueue/serve",
    "config": "{\"runtime\":{\"cpu\":1000,\"gpu\":\"\",\"gpu_count\":1,\"memory\":128,\"image_id\":\"d055bc4ee4ad0e61\",\"gpus\":[\"A10G\"]},\"handler\":\"app:handler\",\"keep_warm_seconds\":10,\"max_pending_tasks\":100,\"task_policy\":{\"max_retries\":3,\"timeout\":3600,\"ttl\":7200},\"workers\":1,\"authorized\":true}",
    "config_version": 0,
    "created_at": "2025-05-22T22:48:57.156033Z",
    "updated_at": "2025-05-22T22:48:57.156033Z"
  },
  "deployment": {
    "name": null,
    "version": null
  }
}

The per-task cost shown in the dashboard isn’t returned by this API. See Task Cost for how to estimate it.

Waiting for a Task to Finish

Poll the API until the status is no longer PENDING, RUNNING, or RETRY:

import time

import requests

TASK_ID = "[TASK_ID]"
HEADERS = {"Authorization": "Bearer [YOUR_AUTH_TOKEN]"}

while True:
    task = requests.get(
        f"https://api.beam.cloud/v2/task/{TASK_ID}/", headers=HEADERS
    ).json()
    if task["status"] not in ("PENDING", "RUNNING", "RETRY"):
        break
    time.sleep(2)

print(task["status"], task["outputs"])

With the Python SDK, Client.get_task_by_id() returns a task object that can wait for the result:

from beam import Client

client = Client(token="[YOUR_AUTH_TOKEN]")
task = client.get_task_by_id("[TASK_ID]")

print(task.status())
result = task.result(wait=True)  # Blocks until the task finishes

To get notified instead of polling, set a callback URL, and Beam will send a POST request to your server when the task finishes.

Cancelling Tasks

Tasks can be cancelled through the api.beam.cloud/v2/task/cancel/ endpoint.

Request

curl -X DELETE --compressed 'https://api.beam.cloud/v2/task/cancel/' \
  -H 'Authorization: Bearer [YOUR_TOKEN]' \
  -H 'Content-Type: application/json' \
  -d '{"task_ids": ["TASK_ID"]}'

This API accepts a list of tasks, which can be passed in like this:

{
  "task_ids": [
    "70101e46-269c-496b-bc8b-1f7ceeee2cce",
    "81bdd7a3-3622-4ee0-8024-733227d511cd",
    "7679fb12-94bb-4619-9bc5-3bd9c4811dca"
  ]
}

Response

200

{}