Metrics · reportMetric

Report a metric value

POST /v1/metrics

A named number reported over time (orders = 42). The app's Insights section shows it with a trend; threshold alerts send an event when it crosses a value. Deciders can report too. With a test API key (lg_test_…) it goes to a test metric of that name (test: true), apart from the live one and out of the long-term history; its threshold alerts send test events.

Who may call it: Agents (API key); humans: Deciders and up
Server: https://api.logu.dev

Parameters#

Name	In	Type	Required	Description
`Logu-Workspace`	header	`string`	optional	Humans only: the workspace to act in (default: your personal workspace). Agents always act in their API key's workspace. · e.g. `wsp_01K7D7Y8Z0B2D4F6H8K0M2P4R6`
`Idempotency-Key`	header	`string`	optional	Send a unique value per operation to retry safely: a retry with the same key and body returns the first result (`Idempotent-Replayed: true`). Per agent, remembered 24 hours. · e.g. `deploy-4821`

Request body#

Content type application/json (required).

A metric value an agent (or a Decider) reports. Strict.

Field	Type	Required	Notes
`project`	`string`	required	1–64 chars · pattern `^[a-z0-9][a-z0-9._-]*$`
`metric`	`string`	required	1–64 chars · pattern `^[a-z0-9][a-z0-9._-]*$`
`value`	`number`	required
`unit`	`string`	optional	0–16 chars
`label`	`string`	optional	1–64 chars

{
  "project": "shop",
  "metric": "orders",
  "value": 42,
  "unit": "orders",
  "label": "Orders today"
}

Example#

curl -s -X POST "https://api.logu.dev/v1/metrics" \
  -H "Authorization: Bearer $LOGU_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"shop","metric":"orders","value":42,"unit":"orders","label":"Orders today"}'

Responses#

201

The metric with its latest value.

{
  "id": "met_01K7DQ4A6C8E0G2J4L6N8Q0S2U",
  "project": "shop",
  "metric": "orders",
  "label": "Orders today",
  "unit": "orders",
  "value": 42,
  "at": "2026-10-12T14:03:11.000Z",
  "agent": {
    "id": "agt_01K7D8F2H4K6M8P0R2T4V6X8Z0",
    "name": "deploy-bot"
  },
  "test": false
}

Response fields

Field	Type	Required	Notes
`id`	`string`	required
`project`	`string`	required
`metric`	`string`	required
`label`	`string \| null`	required
`unit`	`string \| null`	required
`value`	`number`	required
`at`	`string`	required	date-time
`agent`	`AgentRef \| null`	required
`agent.id`	`string`	required
`agent.name`	`string`	required
`test`	`boolean`	required	Reported with a test API key (`lg_test_…`): kept apart from the live metric of the same name, not kept in the long-term history, and its threshold alerts create test events.

Errors#

Every error is {"error":{"code","message","hint","docUrl","requestId"}}: branch on code. See Errors.

Status	Code	Meaning
400	`bad_request`	The request is malformed or a field is invalid (see `issues`).
400	`unknown_field`	The body has a field the endpoint doesn't know (often a typo or snake_case).
401	`unauthorized`	No credentials, or the API key or session is invalid or revoked.
402	`plan_limit`	This is over one of the workspace's plan quotas: asks, events or metric reports this month, stored images, projects or metric names (Free and Pro), or on Free its agents, members and webhook endpoints (only on servers that enforce plan limits), or a Free account that already owns its shared workspaces (always).
402	`ceiling_reached`	The workspace reached one of Logu's cost ceilings (asks, events, metric reports, test traffic or images this month, stored image bytes, projects, metric names or API keys). Unlike `plan_limit`, upgrading doesn't lift it. An account that already owns the most shared workspaces an account may own gets it too.
403	`forbidden`	The caller is authenticated but may not do this (wrong role, or an API key on a human-only endpoint).
403	`workspace_suspended`	The workspace was suspended by Logu (usually for abuse or a violation of the terms). Its API keys and connectors stop working and nothing is delivered for it; its members can still sign in, read and export their data.
404	`not_found`	No such route, or the resource doesn't exist in your workspace.
409	`idempotency_key_in_use`	A request with the same idempotency key is still being processed.
422	`idempotency_key_reused`	The idempotency key was already used with a different request body or endpoint.
429	`rate_limited`	This API key sent too many requests, or a human did too much too fast: sign-in attempts, workspaces created in a day, or a global daily cap on new accounts was reached.
500	`internal_error`	Something went wrong on Logu's side.