Training Rounds API
Endpoints for starting training rounds, checking status, and submitting device updates.
Retrieve current round
GET /api/v1/training/rounds/current
Returns the most recent training round regardless of status. Returns 404 if no rounds have been created yet.
Response
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"round_number": 18,
"status": "active",
"target_devices": 10,
"min_devices": 8,
"participated_devices": 6,
"completed_devices": 4,
"failed_devices": 1,
"global_model_path": "s3://octomil-models/global/round_17.pt",
"aggregated_model_path": null,
"started_at": "2025-07-01T12:15:00Z",
"completed_at": null,
"timeout_at": "2025-07-01T12:20:00Z",
"created_at": "2025-07-01T12:15:00Z"
}
Retrieve round status
GET /api/v1/training/rounds/{round_id}/status
Returns the full status of a training round including participant progress and timing.
Response Fields
| Field | Type | Description |
|---|---|---|
id | string (uuid) | Round UUID |
round_number | integer | Sequential counter |
status | string | pending, active, aggregating, completed, or failed |
target_devices | integer | Devices selected for this round |
min_devices | integer | Minimum updates required |
participated_devices | integer | Devices that have begun local training |
completed_devices | integer | Devices that have submitted updates |
failed_devices | integer | Devices that failed during training |
global_model_path | string | null | S3 path to the distributed global model |
aggregated_model_path | string | null | S3 path to the aggregated result (null until completed) |
started_at | string | null | When the round became active |
completed_at | string | null | When aggregation finished |
timeout_at | string | null | When the round will auto-fail |
Start a round
POST /api/v1/training/rounds/start
Initializes a new federated learning training round. The server selects devices, sets the round to active, and distributes the current global model. Returns 409 Conflict if a round is already in progress.
Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
target_devices | integer | Yes | Number of devices to select |
min_devices | integer | Yes | Minimum updates required before aggregation |
timeout_seconds | integer | No | Seconds before timeout. Default: 300. Range: 60-3600 |
global_model_id | string (uuid) | No | Model to distribute. Default: latest aggregated |
Request
curl -X POST https://api.octomil.com/api/v1/training/rounds/start \
-H "Authorization: Bearer $OCTOMIL_API_KEY" \
-H "Content-Type: application/json" \
-d '{"target_devices": 10, "min_devices": 8, "timeout_seconds": 300}'
Submit an update
POST /api/v1/training/rounds/{round_id}/updates
Upload locally-trained model weights for the given round. Returns 409 Conflict if the round is no longer accepting updates or if this device already submitted.
Body (multipart/form-data)
| Field | Type | Required | Description |
|---|---|---|---|
file | binary | Yes | Serialized model weights file |
num_samples | integer | Yes | Number of local training samples used |
local_loss | number | No | Final local training loss |
local_accuracy | number | No | Final local accuracy (0.0-1.0) |
training_time_seconds | integer | No | Wall-clock training duration in seconds |
Response (201 Created)
{
"id": "c3d4e5f6-a7b8-9012-cdef-345678901234",
"round_id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"device_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"model_path": "s3://octomil-models/updates/round_18/device_a1b2c3d4.pt",
"model_size_bytes": 4521984,
"num_samples": 5000,
"local_loss": 0.3421,
"local_accuracy": 0.8915,
"training_time_seconds": 47,
"created_at": "2025-07-01T12:18:30Z"
}
Errors
| Status | Error | Description |
|---|---|---|
400 | bad_request | Invalid or missing request fields |
401 | unauthorized | Missing or invalid API key |
404 | not_found | Resource does not exist |
409 | conflict | Resource already exists or state conflict |
429 | rate_limited | Too many requests; check Retry-After |
500 | internal_error | Unexpected server error |