task API:
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
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. |
{
"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 theapi.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"]}'
{
"task_ids": [
"70101e46-269c-496b-bc8b-1f7ceeee2cce",
"81bdd7a3-3622-4ee0-8024-733227d511cd",
"7679fb12-94bb-4619-9bc5-3bd9c4811dca"
]
}
Response
200
{}