InstantMLDocs

Metrics and series API

Write scalar metrics, read metric history, request batched series, and inspect rank metrics.

Open .md

Write scalar and rank-aware metrics on the SDK hot path, then read them back as bounded series for charting.

Authenticate with an Authorization: Bearer instantml_... API key or a browser session. Metric writes need the sdk:ingest scope; all reads on this page need export:read.

Write scalar metrics

bash
curl -X POST https://api.instantml.ai/runs/{run_id}/metrics \
  -H "Authorization: Bearer instantml_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: optional-event-id" \
  -d '{
    "metrics": {
      "train/loss": 0.12,
      "eval/accuracy": 0.9
    },
    "step": 1,
    "timestamp": "2026-05-16T00:00:00Z"
  }'

Requires sdk:ingest or a writable browser session.

Validation:

  • Step must be finite and nonnegative.
  • Metric values must be finite numbers.
  • Up to 1,000 metrics per batch.

Response:

json
{ "inserted": 2 }

Read one run's metric history

http
GET /runs/{run_id}/metrics?key=eval/accuracy&start_step=0&end_step=100&limit=1000
Authorization: Bearer instantml_...

Requires export:read. Query parameters:

ParameterMeaning
keyOptional exact metric key.
start_stepOptional lower bound.
end_stepOptional upper bound.
limitMax 5,000.

Read batched metric series

http
POST /api/metrics/series
Authorization: Bearer instantml_...
Content-Type: application/json

{
  "key": "eval/accuracy",
  "run_ids": ["uuid-a", "uuid-b"],
  "limit": 1000,
  "buckets": 512
}

Requires export:read. Use this endpoint for dashboard-style charting. It accepts up to 2,000 run IDs, but the server clamps the effective per-run point limit so one response cannot exceed the maximum returned-point budget.

Request fields:

FieldMeaning
keyRequired metric key.
run_idsRequired run UUIDs, up to 2,000.
limitOptional per-run point limit.
start_stepOptional lower step bound.
end_stepOptional upper step bound.
bucketsOptional M4 downsampling bucket count, 1 to 4,096.

When buckets is set and a series has more than 4 * buckets points, the response uses M4 aggregation instead of a plain prefix limit; the rendered line through the downsampled points is pixel-identical to the line through all raw points. buckets is ignored when start_step or end_step is set — zoomed views use the raw path.

Write rank-aware metrics

http
POST /runs/{run_id}/rank-metrics
Authorization: Bearer instantml_...
Idempotency-Key: optional-event-id
Content-Type: application/json

{
  "metrics": {
    "train/loss": 0.12
  },
  "step": 1,
  "rank": 0,
  "local_rank": 0,
  "world_size": 8,
  "weight": 1024,
  "timestamp": "2026-05-16T00:00:00Z"
}

Requires sdk:ingest. Rank and local rank are zero-based. World size must be between 1 and 512. Weight defaults to 1.0.

Read a rank summary

http
GET /api/runs/{run_id}/rank-metrics/summary?key=train/loss&start_step=0&end_step=1000&limit=1000
Authorization: Bearer instantml_...

Requires export:read. key selects the rank metric, start_step and end_step bound the inclusive step range, and limit caps returned steps. The response includes:

  • Available keys.
  • Reducers by step.
  • Heatmap cells.
  • Outlier rows.
  • Coverage rows.
  • Limits and truncation flags.

The summary is intentionally run-scoped, which keeps the Distributed tab fast for large projects.

Next steps