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


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