> ## 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.

# Get Task Status

### Query 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).

## 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 full runtime configuration for the deployment, returned as a JSON string. |
| `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. |

<Tip>
  To parse `stub.config`, use `json.loads()` or an equivalent JSON decoder in
  your language.
</Tip>

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

```json theme={null}
{
  "id": "07ce4078-bccc-4a42-b530-5f2653484a6a",
  "started_at": "2024-07-22T14:02:28.466278Z",
  "ended_at": "2024-07-22T14:02:28.475954Z",
  "status": "COMPLETE",
  "container_id": "endpoint-d327e987-759d-493e-b3e4-005774bcf998-8b747792",
  "updated_at": "2024-07-22T14:02:28.477026Z",
  "created_at": "2024-07-22T14:02:28.413232Z",
  "outputs": [],
  "stats": {
    "active_containers": 0,
    "queue_depth": 0
  },
  "stub": {
    "id": "d327e987-759d-493e-b3e4-005774bcf998",
    "name": "endpoint/deployment/app:squared",
    "type": "",
    "config": "{\"runtime\":{\"cpu\":1000,\"gpu\":\"\",\"memory\":128,\"image_id\":\"4724a2a2dfb601d8\"},\"handler\":\"app:squared\",\"on_start\":\"\",\"python_version\":\"python3.10\",\"keep_warm_seconds\":180,\"max_pending_tasks\":100,\"callback_url\":\"\",\"task_policy\":{\"max_retries\":0,\"timeout\":180,\"expires\":\"0001-01-01T00:00:00Z\"},\"workers\":1,\"authorized\":false,\"volumes\":null,\"autoscaler\":{\"type\":\"queue_depth\",\"max_containers\":1,\"tasks_per_container\":1}}",
    "config_version": 0,
    "object_id": 0,
    "created_at": "0001-01-01T00:00:00Z",
    "updated_at": "0001-01-01T00:00:00Z"
  }
}
```

### Task Cost

The per-task **Cost** shown in the dashboard is *not* returned by this API — it is currently only available in the dashboard.

To estimate task cost programmatically, multiply the task duration (`ended_at` − `started_at`) by the per-second rates of the CPU, memory, and GPU your app requests. You can find the current rates on the [pricing page](https://www.beam.cloud/pricing).


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