API Reference

REST API & Scoped Tokens

Everything in Observability is also available as a plain REST API — the same data backing your dashboard is queryable directly, and reachable by anything that can make an HTTP request, not just this dashboard. This page documents that API, and a second credential type — scoped read tokens — for safely exposing one slice of your own org's data to your own end-users.

Sessions

List sessions with server-side filtering and pagination.

bash

curl "https://api.niitaka.ai/sessions?agent_id=report-summariser&limit=20" \
  -H "X-API-Key: $NIITAKA_API_KEY"

Filter by arbitrary session tags (JSONB containment — all key/value pairs must match):

bash

curl "https://api.niitaka.ai/sessions?tags=%7B%22user_id%22%3A%22abc123%22%7D" \
  -H "X-API-Key: $NIITAKA_API_KEY"

# tags is a JSON-encoded object, URL-encoded — the example above decodes to:
#   {"user_id": "abc123"}
# All key/value pairs must match (JSONB containment), not an exact-match filter.

Other filters: team_id, status, search, date_start/date_end, environment, limit/offset.

Session detail

Full session metadata plus every event on it.

bash

curl "https://api.niitaka.ai/sessions/sess_abc123" \
  -H "X-API-Key: $NIITAKA_API_KEY"

Session stats

Hero-card aggregates — total, running, cost, error count, agent count.

bash

curl "https://api.niitaka.ai/sessions/stats?days=7" \
  -H "X-API-Key: $NIITAKA_API_KEY"

# → { total, running, total_cost, error_sessions, agent_count, days }

Analytics

Trend and quality analytics, computed with pure SQL aggregation server-side — never a full row export.

bash

curl "https://api.niitaka.ai/analytics/quality?range=7d" \
  -H "X-API-Key: $NIITAKA_API_KEY"

curl "https://api.niitaka.ai/analytics/cost?range=30d" \
  -H "X-API-Key: $NIITAKA_API_KEY"

# range: 24h | 7d | 30d | all

/analytics/cost — spend trend, cost by agent, cost by model, top sessions by cost.
/analytics/quality — error trend, latency trend, per-agent quality table.
/analytics/overview, /analytics/metrics — see the dashboard's own Analytics tab for what these back.

Authentication

The standard credential is your org's API key (X-API-Key) or a dashboard Bearer JWT — see Configuration & Auth. Both grant full read (and, for the API key, write) access to your org's data.

Scoped read tokens

Your org API key is powerful — it reads and writes everything. That's the right credential for your own backend, but the wrong one to hand to your own end-users if you want to build a “here's your own usage” view into your product. Scoped tokens solve that: a read-only credential restricted to a mandatory tag filter, good for a bounded time.

Read-only — never usable for ingestion, regardless of what your org API key can do.
Restricted to a tag filter you set at mint time — every query made with the token has that filter applied unconditionally, even if the caller also supplies a conflicting tags parameter.
Short-lived — capped at 24 hours per token.
Usable only on a small set of read routes: GET /sessions, GET /sessions/{id}, GET /sessions/stats, GET /analytics/cost, GET /analytics/quality. Every other route — including every write endpoint — doesn't recognize this credential at all.

Minting a token

Mint with your org API key (server-to-server), or a dashboard session with the admin or developer role — viewer is rejected, since minting a data-access credential is a sensitive operation.

bash

curl -X POST "https://api.niitaka.ai/scoped-tokens" \
  -H "X-API-Key: $NIITAKA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "tag_filter": {"user_id": "abc123"},
    "ttl_seconds": 3600,
    "label": "condit-user-abc123-dashboard-load"
  }'

# → { id, token, tag_filter, label, created_at, expires_at }
# The raw "token" value is shown once. It cannot be retrieved again after this call —
# store it yourself for the duration you need it (up to expires_at), or mint a new one.

Warning:The raw token is returned once, at creation. There is no way to retrieve it again — if you lose it, revoke it and mint a new one.

Using a token

bash

curl "https://api.niitaka.ai/sessions" \
  -H "X-Scoped-Token: $SCOPED_TOKEN"

# Only sessions matching {"user_id": "abc123"} come back — enforced server-side,
# regardless of any other "tags" query param also supplied on the request.

Listing and revoking

bash

# List this org's active scoped tokens (metadata only — never the raw token again)
curl "https://api.niitaka.ai/scoped-tokens" -H "X-API-Key: $NIITAKA_API_KEY"

# Revoke one early, before its natural expiry
curl -X DELETE "https://api.niitaka.ai/scoped-tokens/<id>" -H "X-API-Key: $NIITAKA_API_KEY"

Example: per-user observability in your own product

The intended shape: your backend holds the org API key server-side (same trust boundary as any other backend secret), tags each of your users' sessions with something identifying them (e.g. {"user_id": "abc123"} at start_session() time), then mints a short-lived scoped token per request — or per dashboard load — restricted to that same tag, and proxies it to your frontend. Your own end-user sees only their own data; Niitaka enforces that boundary server-side, not your own query construction.

Rate limits

Scoped-token reads have their own per-org rate limit, separate from your ingest budget, so this traffic never competes with your own agents' event logging. Exceeding it returns 429. Limits scale with plan tier — see your Analytics settings for your current allowance.

Next steps

Sessions — the dashboard view this same data backs.
Configuration & Auth — credential storage and rotation.

Environments

Sessions

Was this page helpful?

Need help? Contact Support Questions? Contact Sales LLM? Read llms.txt