Monitoring API: metrics, events, and cost

Query platform-level metrics, activity event logs, API performance data, per-agent metrics and summaries, and agent cost data from the Nora Monitoring API.

The Monitoring API gives you observability into the Nora platform and the agents you can access. You can pull a high-level metrics summary, page through the activity event log, query detailed per-agent metrics with time range filters, retrieve pre-aggregated summary statistics, and fetch cost data. Session users follow normal ownership and workspace membership. A workspace API key with monitoring:read is restricted to agents and events in its exact bound workspace, even when the issuing user can access other workspaces.

Platform metrics summary

Return aggregate health and usage metrics for the entire platform as seen by the authenticated user.

GET /monitoring/metrics

Response

number

Total number of accessible agents.

number

Agents currently in running state.

number

Agents currently in deploying state.

number

Agents in queued state.

number

Agents in stopped state.

number

Agents in warning state.

number

Agents in error state.

number

Total number of deployments.

object

Deployment queue job counts.

Show properties

number

Jobs waiting to run.

number

Jobs currently running.

number

Jobs completed.

number

Jobs failed.

curl http://localhost:8080/api/monitoring/metrics \
  -H "Authorization: Bearer $TOKEN"

{
  "totalAgents": 4,
  "activeAgents": 2,
  "deployingAgents": 0,
  "queuedAgents": 0,
  "stoppedAgents": 1,
  "warningAgents": 0,
  "errorAgents": 1,
  "totalDeployments": 7,
  "queue": { "waiting": 0, "active": 0, "completed": 0, "failed": 0 }
}

Fleet needs-attention roll-up

Return only the agents that need an operator’s attention right now, with the reasons why. Derived at read time from existing state — no extra configuration. Use it to drive a triage view instead of scanning every agent. Requires the monitoring:read scope. Detected reasons: error and budget_paused (severity error); warning, stuck_deploying (queued/deploying over 10 minutes), budget_warning (a running agent crossed a budget soft threshold), and telemetry_stalled (a running agent reported no container telemetry for over 5 minutes).

GET /monitoring/fleet-status

Response

string

ISO timestamp the roll-up was computed.

number

Total number of accessible agents evaluated.

number

Number of agents needing attention.

array

Agents needing attention, errors first. Each has agentId, name, status, severity, and a reasons array of { code, severity, label }.

curl http://localhost:8080/api/monitoring/fleet-status \
  -H "Authorization: Bearer $TOKEN"

{
  "generatedAt": "2026-06-12T12:00:00.000Z",
  "total": 4,
  "attentionCount": 2,
  "agents": [
    {
      "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Billing bot",
      "status": "stopped",
      "severity": "error",
      "reasons": [
        { "code": "budget_paused", "severity": "error", "label": "Paused — budget cap reached" }
      ]
    },
    {
      "agentId": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
      "name": "Scraper",
      "status": "deploying",
      "severity": "warning",
      "reasons": [
        { "code": "stuck_deploying", "severity": "warning", "label": "Stuck deploying for 18m" }
      ]
    }
  ]
}

Activity event log

Return a chronological log of activity events. When you supply agentId the results are filtered to that agent; otherwise all events across your agents are returned.

GET /monitoring/events

Query parameters

string

Filter events to a specific agent UUID.

number

default:"50"

Maximum number of events to return, ordered newest first.

string

Filter events to a specific event type slug.

string

Full-text filter across event messages.

string

Inclusive start date (YYYY-MM-DD) for the event window.

string

Inclusive end date (YYYY-MM-DD) for the event window.

number

Page number for paginated results (1-based).

Supplying any of page, search, type, from, or to switches the response to a pagination envelope (with limit clamped to 10–100). Without those filters, a flat array is returned (limit 1–100, default 50).

Response

string

Event UUID.

string

Event type slug, e.g. agent_deployed, agent_redeployed.

string

Human-readable description of the event.

object

Additional context for the event.

Show properties

string

Related agent UUID, when applicable.

string

ISO 8601 event timestamp.

curl "http://localhost:8080/api/monitoring/events?limit=20" \
  -H "Authorization: Bearer $TOKEN"

curl "http://localhost:8080/api/monitoring/events?agentId=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=10" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "g8h9i0j1-k2l3-4567-mnop-456789012345",
    "type": "agent_deployed",
    "message": "Agent \"My Agent\" (OpenClaw + Docker) queued for deployment",
    "metadata": { "agentId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890" },
    "created_at": "2025-03-10T09:00:05.000Z"
  }
]

API performance data

Return raw API performance metric records. Useful for building latency dashboards or debugging slow endpoints.

GET /monitoring/performance

Unlike the other /monitoring/* endpoints, this one requires a platform-admin session. Workspace API keys are rejected with 403 session_required even when issued by an admin; non-admin sessions receive 403 {"error": "Admin access required"}.

Query parameters

string

ISO 8601 start timestamp. Defaults to 24 hours ago.

Response

Each record represents a single API call that was instrumented.

number

Measured value (typically response time in ms).

object

Context for the measurement, such as path and method.

string

ISO 8601 timestamp when the metric was recorded.

curl "http://localhost:8080/api/monitoring/performance?since=2025-03-10T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "value": 42,
    "metadata": { "method": "GET", "path": "/agents", "status": 200 },
    "recorded_at": "2025-03-10T09:01:00.000Z"
  }
]

Agent metrics

Return time-series metric records for a specific agent. You can filter by metric type and specify an exact time range.

GET /agents/:id/metrics

Path parameters

string

required

Agent UUID.

Query parameters

string

Metric type filter, e.g. cpu, memory, tokens. When omitted, all types are returned.

string

ISO 8601 start of the time range. Defaults to 24 hours ago.

string

ISO 8601 end of the time range. Defaults to now.

Response

string

Metric record UUID.

string

Agent UUID.

string

Metric category slug.

number

Numeric metric value.

object

Additional context for the metric.

string

ISO 8601 timestamp.

curl "http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/metrics?type=tokens&since=2025-03-10T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

[
  {
    "id": "h9i0j1k2-l3m4-5678-nopq-567890123456",
    "agent_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "metric_type": "tokens",
    "value": 1240,
    "metadata": { "model": "gpt-4o", "direction": "completion" },
    "recorded_at": "2025-03-10T09:10:00.000Z"
  }
]

Agent metrics summary

Return pre-aggregated summary statistics for an agent. Useful for dashboards that need totals without querying the full time-series.

GET /agents/:id/metrics/summary

Path parameters

string

required

Agent UUID.

Response

number

Total LLM tokens consumed by this agent.

number

Total LLM API requests made.

number

Average LLM response latency in milliseconds.

string

ISO 8601 timestamp of the most recent metric record.

curl http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/metrics/summary \
  -H "Authorization: Bearer $TOKEN"

{
  "total_tokens": 48200,
  "total_requests": 312,
  "avg_response_ms": 1840,
  "last_active_at": "2025-03-10T09:10:00.000Z"
}

Agent cost

Return estimated token-cost data for a specific agent. Token usage is grouped by model when runtime responses include model metadata; older rows without metadata appear as Unknown model.

GET /agents/:id/cost?period_days=30

Use period_start and period_end instead of period_days for a custom UTC date window.

Path parameters

string

required

Agent UUID.

Response

number

Estimated token cost in USD.

number

Total estimated token cost in USD.

number

Input or prompt tokens recorded in the period.

number

Output or completion tokens recorded in the period.

number

Total tokens recorded in the period.

object

Token pricing details.

Show properties

object

Fallback token rate and per-model token usage rows.

string

Start of the reporting period (ISO 8601).

string

End of the reporting period (ISO 8601).

curl http://localhost:8080/api/agents/a1b2c3d4-e5f6-7890-abcd-ef1234567890/cost \
  -H "Authorization: Bearer $TOKEN"

{
  "token_cost": 0.62,
  "total_cost": 0.62,
  "input_tokens": 120000,
  "output_tokens": 42000,
  "total_tokens": 162000,
  "cost_details": {
    "tokens": {
      "fallback_per_1k": 0.002,
      "models": [
        {
          "model": "openai/gpt-5.5",
          "provider": "openai",
          "input_tokens": 120000,
          "output_tokens": 42000,
          "total_tokens": 162000,
          "rate_source": "model",
          "token_cost": 0.62
        }
      ]
    }
  },
  "periodStart": "2025-03-01T00:00:00.000Z",
  "periodEnd": "2025-03-31T23:59:59.000Z"
}

Status	Condition
`404`	Agent not found

Getting started

Concepts

Configuration

Guides

API Reference

Support

Monitoring

Monitoring API: metrics, events, and cost

Platform metrics summary

Response

Fleet needs-attention roll-up

Response

Activity event log

Query parameters

Response

API performance data

Query parameters

Response

Agent metrics

Path parameters

Query parameters

Response

Agent metrics summary

Path parameters

Response

Agent cost

Path parameters

Response

​Monitoring API: metrics, events, and cost

​Platform metrics summary

​Response

​Fleet needs-attention roll-up

​Response

​Activity event log

​Query parameters

​Response

​API performance data

​Query parameters

​Response

​Agent metrics

​Path parameters

​Query parameters

​Response

​Agent metrics summary

​Path parameters

​Response

​Agent cost

​Path parameters

​Response

Monitoring API: metrics, events, and cost

Platform metrics summary

Response

Fleet needs-attention roll-up

Response

Activity event log

Query parameters

Response

API performance data

Query parameters

Response

Agent metrics

Path parameters

Query parameters

Response

Agent metrics summary

Path parameters

Response

Agent cost

Path parameters

Response