Documentation / Metrics Export API

Metrics Export API

Meridian's canonical vendor-neutral pull surface for monitoring platforms. Schema version remains 1.0.

Interactive API reference · Download openapi.json

Versioning & Stability

Schema 1.0 covers the two canonical endpoints below. /api/v1/lm/agents and /api/v1/lm/metrics are permanent aliases.

Evolution within 1.x is additive only: optional fields may be added and consumers must ignore unknown fields. Existing fields will not be renamed, removed, retyped, or given new semantics within 1.x.

Breaking changes use a new schema version and new versioned routes. The prior version remains available for at least 12 months after notice in the changelog and by key-owner email. Authentication with a bearer integration key and metrics:read is part of this contract.

Authentication

Call https://api.onaro.io with Authorization: Bearer mrk_live_…. Keys have only metrics:read, are tenant-bound, may be workspace-scoped, and store only a SHA-256 hash.

Endpoints

• GET /api/v1/metrics/agents — discovery, 10 requests/minute.
• GET /api/v1/metrics/current — collection, 30 requests/minute.

/api/v1/lm/agents and /api/v1/lm/metrics are stable aliases. Aliases share handlers, rate-limit buckets, and caches with canonical routes.

Contract

Discovery returns schema_version, as_of, and agents. Current metrics returns those envelope fields plus currency, per-agent metrics, and portal. The portal object is the tenant-level rollup; its name is fixed in schema 1.0.

Attribute semantics follow OASA. This is a Meridian product API, not part of the OASA specification.

Agent fields include current-hour, today, and month-to-date spend; token rates; task count; cost per task; optional budget burn; and optional anomaly score. Null budget and cold-start anomaly values mean No Data, not zero.

Caching and currency

Discovery is cached for five minutes and current metrics for 60 seconds after authentication. Currency is configured on the key. Unsupported rates fail explicitly; Meridian never substitutes an unsupported 1:1 conversion.

Limits and cache windows are operational parameters. Successful responses report X-RateLimit-Limit and X-RateLimit-Remaining; 429 responses also report Retry-After.

Key lifecycle

Up to five active keys are allowed. Rotation gives the prior key a 24-hour grace period; revocation is immediate. Rate-limit responses include Retry-After.

See the public changelog or contact hello@onaro.io with compatibility questions.