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 both the Nora platform and your individual agents. You can pull a high-level platform 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. All metrics are scoped to agents you own — you cannot query data for another user’s agents.

Platform metrics summary

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

GET /monitoring/metrics

Response

agents_total

number

Total number of agents owned by the user.

agents_running

number

Agents currently in running state.

agents_stopped

number

Agents in stopped state.

agents_error

number

Agents in error or warning state.

events_today

number

Number of activity events recorded in the last 24 hours.

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

{
  "agents_total": 4,
  "agents_running": 2,
  "agents_stopped": 1,
  "agents_error": 1,
  "events_today": 37
}

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

generatedAt

string

ISO timestamp the roll-up was computed.

total

number

Total number of accessible agents evaluated.

attentionCount

number

Number of agents needing attention.

agents

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

agentId

string

Filter events to a specific agent UUID.

limit

number

default:"50"

Maximum number of events to return, ordered newest first.

Response

string

Event UUID.

type

string

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

message

string

Human-readable description of the event.

metadata

object

Additional context for the event.

Show properties

agentId

string

Related agent UUID, when applicable.

created_at

string

ISO 8601 event timestamp.

curl "http://localhost:8080/api/monitoring/events?limit=20" \
  -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

Query parameters

since

string

ISO 8601 start timestamp. Defaults to 24 hours ago.

Response

Each record represents a single API call that was instrumented.

value

number

Measured value (typically response time in ms).

metadata

object

Context for the measurement, such as path and method.

recorded_at

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

type

string

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

since

string

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

until

string

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

Response

string

Metric record UUID.

agent_id

string

Agent UUID.

metric_type

string

Metric category slug.

value

number

Numeric metric value.

metadata

object

Additional context for the metric.

recorded_at

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

total_tokens

number

Total LLM tokens consumed by this agent.

total_requests

number

Total LLM API requests made.

avg_response_ms

number

Average LLM response latency in milliseconds.

last_active_at

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

token_cost

number

Estimated token cost in USD.

total_cost

number

Total estimated token cost in USD.

input_tokens

number

Input or prompt tokens recorded in the period.

output_tokens

number

Output or completion tokens recorded in the period.

total_tokens

number

Total tokens recorded in the period.

cost_details

object

Token pricing details.

Show properties

tokens

object

Fallback token rate and per-model token usage rows.

periodStart

string

Start of the reporting period (ISO 8601).

periodEnd

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

​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