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

# Workloads

> List, retrieve, and get statistics for GPU workloads

## List Workloads

Retrieve a paginated list of workloads with optional filtering.

<Note>
  Results are automatically filtered based on your role and team access.
</Note>

```bash theme={null}
GET /v1/workloads
```

### Query Parameters

| Parameter         | Type    | Description                                                                |
| ----------------- | ------- | -------------------------------------------------------------------------- |
| `organization_id` | string  | Filter by organization                                                     |
| `initiative_id`   | string  | Filter by team                                                             |
| `status`          | string  | Filter by status: `pending`, `running`, `completed`, `failed`, `cancelled` |
| `submitted_by`    | string  | Filter by user who submitted the workload                                  |
| `is_managed`      | boolean | Filter managed vs unmanaged workloads                                      |
| `start_date`      | string  | Filter workloads submitted after this date (ISO 8601)                      |
| `end_date`        | string  | Filter workloads submitted before this date (ISO 8601)                     |
| `limit`           | integer | Number of results per page (1-100, default: 20)                            |
| `next_token`      | string  | Pagination cursor from previous response                                   |

### Example Request

```bash theme={null}
curl -X GET "https://api.usechamber.io/v1/workloads?status=running&limit=10" \
  -H "Authorization: Bearer <token>" \
  -H "X-Organization-Id: <org-id>"
```

### Example Response

```json theme={null}
{
  "data": {
    "workloads": [
      {
        "workload_id": "wl_abc123",
        "name": "training-job-001",
        "status": "running",
        "submitted_by": "user@example.com",
        "initiative_id": "init_xyz",
        "instance_type": "p4d.24xlarge",
        "gpu_count": 8,
        "submitted_at": "2024-01-15T10:30:00Z",
        "started_at": "2024-01-15T10:32:00Z"
      }
    ]
  },
  "metadata": {
    "next_token": "eyJ...",
    "total_count": 45
  },
  "request_id": "req_abc123"
}
```

***

## Get Workload

Retrieve details for a specific workload.

```bash theme={null}
GET /v1/workloads/{workload_id}
```

### Path Parameters

| Parameter     | Type   | Description                    |
| ------------- | ------ | ------------------------------ |
| `workload_id` | string | The unique workload identifier |

### Example Request

```bash theme={null}
curl -X GET "https://api.usechamber.io/v1/workloads/wl_abc123" \
  -H "Authorization: Bearer <token>" \
  -H "X-Organization-Id: <org-id>"
```

### Example Response

```json theme={null}
{
  "data": {
    "workload_id": "wl_abc123",
    "name": "training-job-001",
    "status": "running",
    "submitted_by": "user@example.com",
    "initiative_id": "init_xyz",
    "instance_type": "p4d.24xlarge",
    "gpu_count": 8,
    "submitted_at": "2024-01-15T10:30:00Z",
    "started_at": "2024-01-15T10:32:00Z",
    "completed_at": null,
    "duration_seconds": 3600,
    "gpu_hours_used": 8.0,
    "exit_code": null,
    "is_managed": true,
    "cluster_id": "cluster_prod1",
    "namespace": "ml-training"
  },
  "request_id": "req_abc123"
}
```

***

## Get Workload Statistics

Retrieve aggregated statistics across workloads.

```bash theme={null}
GET /v1/workloads/stats
```

### Query Parameters

| Parameter       | Type   | Description                                                                                   |
| --------------- | ------ | --------------------------------------------------------------------------------------------- |
| `time_range`    | string | Predefined range: `today`, `this_week`, `this_month`, `last_7_days`, `last_30_days`, `custom` |
| `start_date`    | string | Start date for custom range (ISO 8601)                                                        |
| `end_date`      | string | End date for custom range (ISO 8601)                                                          |
| `group_by`      | string | Group results by: `submitted_by`, `initiative_id`, `instance_type`                            |
| `initiative_id` | string | Filter to specific team                                                                       |

### Example Request

```bash theme={null}
curl -X GET "https://api.usechamber.io/v1/workloads/stats?time_range=last_7_days&group_by=initiative_id" \
  -H "Authorization: Bearer <token>" \
  -H "X-Organization-Id: <org-id>"
```

### Example Response

```json theme={null}
{
  "data": {
    "summary": {
      "total_workloads": 156,
      "total_gpu_hours": 2450.5,
      "average_duration_seconds": 7200,
      "success_rate": 0.94
    },
    "grouped": [
      {
        "initiative_id": "init_ml_team",
        "workload_count": 89,
        "gpu_hours": 1200.0,
        "success_rate": 0.96
      },
      {
        "initiative_id": "init_research",
        "workload_count": 67,
        "gpu_hours": 1250.5,
        "success_rate": 0.91
      }
    ]
  },
  "request_id": "req_abc123"
}
```