> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beam.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Querying Task Status

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

```sh theme={null}
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](/v2/reference/platform-api).

## 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](/v2/task-queue/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`](/v2/topics/context).

## 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](/v2/topics/timeouts-and-retries). |
| `ERROR` | The task did not complete successfully. |

### Request

```sh theme={null}
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:

```json theme={null}
{
  "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
  }
}
```

<Note>
  The per-task cost shown in the dashboard isn't returned by this API. See [Task
  Cost](/v2/reference/api-docs/tasks/tasks-status#task-cost) for how to estimate
  it.
</Note>

## Waiting for a Task to Finish

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

```python theme={null}
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()`](/v2/reference/py-sdk#client) returns a task object that can wait for the result:

```python theme={null}
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](/v2/task-queue/callbacks), 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

```bash theme={null}
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:

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

### Response

`200`

```json theme={null}
{}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.