> ## 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}/
```

### 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 `max_retries` is provided in the function 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. **For endpoints, this usually occurs when the task does not start running before the request timeout (180 seconds).** |
| `FAILED`    | 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"
  }
}
```