# Metrics and series API

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:

| Parameter | Meaning |
| --- | --- |
| `key` | Optional exact metric key. |
| `start_step` | Optional lower bound. |
| `end_step` | Optional upper bound. |
| `limit` | Max 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:

| Field | Meaning |
| --- | --- |
| `key` | Required metric key. |
| `run_ids` | Required run UUIDs, up to 2,000. |
| `limit` | Optional per-run point limit. |
| `start_step` | Optional lower step bound. |
| `end_step` | Optional upper step bound. |
| `buckets` | Optional 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

- [Log metrics from the SDK](/docs/sdk/metrics-steps.md)
- [Track distributed training ranks](/docs/sdk/distributed-training.md)
- [Create runs and query summaries](/docs/api/projects-runs.md)
- [Handle errors, pagination, and limits](/docs/api/errors-and-limits.md)
- [Chart metrics in the dashboard](/docs/dashboard/metrics-charts.md)

## Agent navigation

- [Docs index](/llms.txt)
- [Full docs bundle](/llms-full.txt)

### Get Started

- [Overview](/docs/index.md)
- [Quickstart](/docs/quickstart.md)
- [Core Concepts](/docs/concepts/core-concepts.md)
- [Pricing](/docs/pricing.md)
- [Benchmarks](/docs/benchmarks.md)
- [Examples](/docs/guides/examples.md)
- [Troubleshooting](/docs/troubleshooting.md)

### SDK

- [Installation Auth](/docs/sdk/installation-auth.md)
- [Logging](/docs/sdk/logging.md)
- [Tracing](/docs/sdk/tracing.md)
- [Metrics Steps](/docs/sdk/metrics-steps.md)
- [Config Tags Notes](/docs/sdk/config-tags-notes.md)
- [Artifacts Checkpoints](/docs/sdk/artifacts-checkpoints.md)
- [Rich Objects](/docs/sdk/rich-objects.md)
- [Distributed Training](/docs/sdk/distributed-training.md)
- [Console System Integrations](/docs/sdk/console-system-integrations.md)
- [Reliability](/docs/sdk/reliability.md)
- [Cli Login](/docs/sdk/cli-login.md)
- [Querying Data](/docs/sdk/querying-data.md)
- [Agent Mcp](/docs/sdk/agent-mcp.md)
- [Examples Patterns](/docs/sdk/examples-patterns.md)

### Integrations

- [Overview](/docs/integrations/overview.md)
- [Pytorch Lightning](/docs/integrations/pytorch-lightning.md)
- [Huggingface Transformers](/docs/integrations/huggingface-transformers.md)
- [Keras](/docs/integrations/keras.md)
- [Wandb](/docs/integrations/wandb.md)

### Dashboard

- [Tour](/docs/dashboard/tour.md)
- [Organizations Workspaces](/docs/dashboard/organizations-workspaces.md)
- [Runs Workspace](/docs/dashboard/runs-workspace.md)
- [Metrics Charts](/docs/dashboard/metrics-charts.md)
- [Run Detail](/docs/dashboard/run-detail.md)
- [Traces](/docs/dashboard/traces.md)
- [Compare Runs](/docs/dashboard/compare-runs.md)
- [Research Dashboards](/docs/dashboard/research-dashboards.md)
- [Artifacts Files](/docs/dashboard/artifacts-files.md)
- [Run Health](/docs/dashboard/alerts.md)
- [Datasets](/docs/dashboard/datasets.md)
- [Checkpoints](/docs/dashboard/checkpoints.md)
- [Reports](/docs/dashboard/reports.md)
- [Settings Api Keys](/docs/dashboard/settings-api-keys.md)
- [Api Tab](/docs/dashboard/api-tab.md)
- [Onboarding Team Billing](/docs/dashboard/onboarding-team-billing.md)

### Data

- [Imports](/docs/guides/imports.md)
- [W&B alternative](/docs/guides/wandb-alternative.md)
- [InstantML vs MLflow](/docs/guides/instantml-vs-mlflow.md)
- [W&B import guide](/docs/guides/wandb-import-guide.md)
- [W&B and Neptune imports](/docs/guides/wandb-neptune-imports.md)
- [Export Usage Limits](/docs/guides/export-usage-limits.md)
- [Pricing Limits Billing](/docs/guides/pricing-limits-billing.md)
- [Auth Billing Storage](/docs/guides/auth-billing-storage.md)
- [Customer Owned Clickhouse](/docs/guides/customer-owned-clickhouse.md)
- [Observability](/docs/guides/observability.md)

### API

**Practical API guides**

- [Authentication](/docs/api/authentication.md)
- [Errors And Limits](/docs/api/errors-and-limits.md)
- [Health Observability](/docs/api/health-observability.md)
- [Projects Runs](/docs/api/projects-runs.md)
- [Metrics Series](/docs/api/metrics-series.md) (current page)
- [Attributes Objects](/docs/api/attributes-objects.md)
- [Artifacts](/docs/api/artifacts.md)
- [Reports](/docs/api/reports.md)
- [Iframe Embeds](/docs/api/iframe-embeds.md)
- [Import Export Usage](/docs/api/import-export-usage.md)
- [Dashboard Control State](/docs/api/dashboard-control-state.md)
**Architecture**

- [System Overview](/docs/architecture/system-overview.md)
- [Service Planes](/docs/architecture/service-planes.md)
- [Storage Model](/docs/architecture/storage-model.md)
- [Google Clickhouse](/docs/architecture/google-clickhouse.md)
- [Auth Tenancy](/docs/architecture/auth-tenancy.md)
- [Schema Reference](/docs/architecture/schema-reference.md)

### API Reference

- [API Reference](/docs/api-reference.md)