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.

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 in JSON format.
`stub.config_version`	integer	The version number of the deployment stub configuration.
`stub.object_id`	integer	The object identifier associated with the deployment stub.
`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.

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",
      "on_start": "",
      "on_deploy": "",
      "on_deploy_stub_id": "",
      "python_version": "python3",
      "keep_warm_seconds": 10,
      "max_pending_tasks": 100,
      "callback_url": "",
      "task_policy": {
        "max_retries": 3,
        "timeout": 3600,
        "expires": "0001-01-01T00:00:00Z",
        "ttl": 7200
      },
      "workers": 1,
      "concurrent_requests": 1,
      "authorized": true,
      "volumes": null,
      "autoscaler": {
        "type": "queue_depth",
        "max_containers": 1,
        "tasks_per_container": 1,
        "min_containers": 0
      },
      "extra": {},
      "checkpoint_enabled": false,
      "work_dir": "",
      "entry_point": null,
      "ports": null
    },
    "config_version": 0,
    "created_at": "2025-05-22T22:48:57.156033Z",
    "updated_at": "2025-05-22T22:48:57.156033Z"
  },
  "deployment": {
    "name": null,
    "version": null
  }
}

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

{}

Start Here

Customizing Container Images

Managing Data

Scaling & Performance

Sandboxes

Endpoints and Web Servers

Task Queues

One-Off Functions

Hosting Containers

Operations

Advanced Topics

Self-Hosting

Resources

Security

Querying Task Status

Task Statuses

Request

Response

Cancelling Tasks

Request

Response

​Task Statuses

​Request

​Response

​Cancelling Tasks

​Request

​Response

Task Statuses

Request

Response

Cancelling Tasks

Request

Response