Skip to main content

Training API

Create, monitor, and manage training runs. Run operations require an API key; the account is derived from that key. X-Account-ID is optional and, if supplied, must match the key's account. The public model-config catalog is unauthenticated.

Base URL: https://api.colabhive.com/api/builder/v1

Training Runs​

Create Training Run​

POST /training/runs

For retry-safe creation, send Idempotency-Key with a UUID value. The key is scoped to the account and operation for 24 hours. Repeating the same request returns the original response with Idempotency-Replayed: true; reusing the key with a different body returns HTTP 409.

Request:

{
  "job_name": "my-model",
  "model_config_id": "xgboost-regression",
  "dataset_id": "DATASET_UUID",
  "hyperparameters": {
    "n_estimators": 200,
    "max_depth": 6
  },
  "operating_mode": "balanced",
  "hardware_preference": "auto"
}

operating_mode: eco | balanced | performance
hardware_preference: auto | cpu_only | gpu_only | gpu_preferred

Response:

{
  "job_id": "uuid",
  "status": "pending",
  "message": "Job queued for processing",
  "estimated_cost_credits": null,
  "queue_position": 1
}

job_id is the canonical JSON field. Route templates retain {run_id} for compatibility; both refer to the same UUID. In the Python SDK, use job.id, which resolves job_id and the legacy run_id alias safely.

Python SDK:

job = client.training.create(
    model="xgboost-regression",
    dataset_id="DATASET_ID",
    job_name="my-model",
    hyperparameters={"n_estimators": 200},
)
print(job.id, job.status)

For LLM fine-tuning with llm-qlora-finetune, see the LLM Fine-Tuning Guide.

Retrain on top of an existing model (first-class base)​

Two optional first-class fields let a run start from any trained or merged model instead of the base defined by the model_config:

FieldTypeNotes
baseArtifactRefmodel_version / job / storage → retrain-on-top (staged as the base). hf or omitted → current behavior.
parent_job_idstring | nullOptional lineage parent; derived from base if not provided.
{
  "job_name": "domain-expert-v2",
  "model_config_id": "MODEL_CONFIG_UUID",
  "dataset_id": "DATASET_UUID",
  "base": { "type": "model_version", "version_id": "MERGED_OR_TRAINED_VERSION_UUID" },
  "hyperparameters": { "learning_rate": 0.0002, "num_epochs": 3, "adapter": "qlora" }
}

With base set, hyperparameters carries only hyperparameters — the base and staging are derived from base. See the Merge & Retrain API for the full contract.

List Training Runs​

GET /training/runs

Query params:

  • status (optional): pending | running | completed | failed | cancelled
  • limit (optional, default 20, max 100)
  • cursor (optional): opaque cursor from a previous page — cursor pagination, not offset

Python SDK:

# Cursor pagination
runs = client.training.list(limit=50)
for r in runs:
    print(r.run_id, r.status)

Get Training Run​

GET /training/runs/{run_id}

Response fields:

  • run_id, status, model_config_id, dataset_id
  • created_at, started_at, completed_at
  • hyperparameters, metrics, error_message

Python SDK:

job = client.training.get("RUN_ID")
print(job.status, job.metrics)

Get Training Logs​

GET /training/runs/{run_id}/logs

Returns training logs as a list of timestamped lines.

Response:

{
  "run_id": "uuid",
  "logs": [
    {"timestamp": "2026-01-01T00:01:00Z", "message": "Epoch 1/10 — loss: 0.34"},
    {"timestamp": "2026-01-01T00:02:00Z", "message": "Epoch 2/10 — loss: 0.28"}
  ]
}

Get Training Metrics​

GET /training/runs/{run_id}/metrics

Returns per-epoch metrics for the completed run.

Response:

{
  "run_id": "uuid",
  "metrics": {
    "mae": 42.3,
    "rmse": 58.1,
    "r2": 0.91,
    "epochs": [
      {"epoch": 1, "train_loss": 0.34, "val_loss": 0.38},
      {"epoch": 2, "train_loss": 0.28, "val_loss": 0.31}
    ]
  }
}

Python SDK:

job.wait()
print(job.metrics)

Get Training Events​

GET /training/runs/{run_id}/events

Returns a timeline of events (state transitions, errors, milestones).

Response:

{
  "run_id": "uuid",
  "events": [
    {"event_type": "queued", "timestamp": "2026-01-01T00:00:00Z"},
    {"event_type": "started", "timestamp": "2026-01-01T00:00:30Z"},
    {"event_type": "completed", "timestamp": "2026-01-01T00:05:00Z"}
  ]
}

Cancel Training Run​

POST /training/runs/{run_id}/cancel

Cancels a run in pending or running state.

Response:

{"run_id": "uuid", "status": "cancelled"}

cURL:

curl -X POST "https://api.colabhive.com/api/builder/v1/training/runs/{RUN_ID}/cancel" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY"

Delete Training Run​

DELETE /training/runs/{run_id}

Permanently deletes a training run and its associated artifacts. Only allowed for completed, failed, or cancelled runs.

Python SDK:

client.training.delete("RUN_ID")

Merge Models​

POST /training/merges

Merge N trained models/adapters into a base to produce a new servable model_version (weight arithmetic on CPU — no GPU). A merge is a job (job_type=merge) and counts against your training quota. Full request/response contract, methods (adapter_merge / slerp / ties / dare), and the shared ArtifactRef type are documented in the Merge & Retrain API.

Quick reference:

curl -X POST "https://api.colabhive.com/api/builder/v1/training/merges" \
  -H "Content-Type: application/json" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"name": "qwen-domain-base", "adapters": [{"type": "model_version", "version_id": "ADAPTER_VERSION_UUID"}]}'

Model Artifacts​

List Artifacts​

GET /training/runs/{run_id}/artifacts

Response:

{
  "job_id": "uuid",
  "artifacts": [
    {"filename": "model.pkl", "size_bytes": 15234567, "last_modified": "2026-01-01T00:05:00Z"},
    {"filename": "config.json", "size_bytes": 1234, "last_modified": "2026-01-01T00:05:00Z"}
  ],
  "total_files": 2,
  "total_size_bytes": 15235801
}

Python SDK:

artifacts = client.training.artifacts("RUN_ID")
for a in artifacts:
    print(a.filename, f"{a.size_mb} MB")

Get Download URLs​

GET /training/runs/{run_id}/artifacts/download-urls

Query params:

  • files (optional): Comma-separated filenames (e.g. files=model.pkl,config.json)
  • expiration (optional): URL TTL in seconds (default: 3600, min: 300, max: 86400)

Response:

{
  "job_id": "uuid",
  "download_urls": [
    {
      "filename": "model.pkl",
      "size_bytes": 15234567,
      "download_url": "https://...",
      "expires_in_seconds": 3600
    }
  ]
}

Python SDK:

# Download all artifacts to disk
paths = client.training.download("RUN_ID", output_dir="./my-model")

# Download specific files
paths = client.training.download("RUN_ID", files=["model.pkl"], output_dir="./my-model")

Register for Inference​

POST /training/runs/{run_id}/register-for-inference

Promotes a completed training run to an inference endpoint. See the Model Registration Guide for the full workflow, schema requirements, and visibility options.

Quick reference:

curl -X POST "https://api.colabhive.com/api/builder/v1/training/runs/{RUN_ID}/register-for-inference" \
  -H "Content-Type: application/json" \
  -H "X-Account-ID: YOUR_ACCOUNT_ID" \
  -H "X-API-Key: YOUR_API_KEY" \
  -d '{"name": "my-model", "description": "My model", "visibility": "account"}'

Model Configs (Catalog)​

List Model Configs​

GET /training/model-configs

Returns the live catalog of all trainable models (driven by DB, always up to date).

Query params:

  • active_only (optional, default true)
  • framework (optional): xgboost | lightgbm | sklearn | pytorch | transformers | etc.
  • category (optional): ml_classical | time_series | deep_learning | nlp | etc.

Response:

{
  "model_configs": [
    {
      "model_id": "xgboost-regression",
      "display_name": "XGBoost Regression (GPU)",
      "framework": "xgboost",
      "description": "Gradient boosting for regression",
      "requires_gpu": true,
      "vram_required_mb": 4096,
      "is_active": true
    }
  ]
}

Python SDK:

configs = client.training.model_configs(active_only=True)
for c in configs:
    print(c.model_id, c.display_name, c.framework)

Get Model Config​

GET /training/model-configs/{model_id}

Returns full metadata for a single model config, including hyperparameter definitions.

Response:

{
  "model_id": "xgboost-regression",
  "display_name": "XGBoost Regression (GPU)",
  "framework": "xgboost",
  "description": "...",
  "user_configurable_params": [
    {"name": "n_estimators", "type": "integer", "default": 100, "description": "Number of trees"},
    {"name": "max_depth", "type": "integer", "default": 6, "description": "Tree depth"}
  ],
  "requires_gpu": true,
  "vram_required_mb": 4096,
  "is_active": true
}

Get Model Config Schema​

GET /training/model-configs/{model_id}/schema

Returns the JSON Schema for hyperparameters of a specific model config. Use this to validate your hyperparameters object before creating a run.

Response:

{
  "model_id": "xgboost-regression",
  "schema": {
    "type": "object",
    "properties": {
      "n_estimators": {"type": "integer", "minimum": 10, "maximum": 5000, "default": 100},
      "max_depth": {"type": "integer", "minimum": 1, "maximum": 20, "default": 6},
      "learning_rate": {"type": "number", "minimum": 0.001, "maximum": 1.0, "default": 0.1}
    }
  }
}

Current Operational Contract​

  • Create-run and create-merge requests support Idempotency-Key for retry-safe submission.
  • Run status, logs, metrics and events remain pollable. A feature-gated outbound webhook private preview adds terminal events for training runs and merges; it is not part of the default published OpenAPI, so polling remains the universal fallback. No SSE/WebSocket training event contract is published today.
  • The public contract does not promise a retry count, preemption behavior, checkpoint recovery, or reserved-capacity guarantee across every runtime.
  • Estimated cost and queue position may be returned at submission, but there is no published reservation or final-price guarantee.
  • Logs do not yet publish a platform-wide truncation, retention or pagination guarantee.

Treat those behaviors as deployment-specific until they are included in the public contract.

See Also​