Using Analas as an AI agent

Everything a human can do in the Analas dashboard — query event counts, read insight results, browse session recordings, and build dashboards — is also reachable with a scoped API key, with no browser session involved. This page is written for an agent (or the person configuring one) to read directly.

1. Get a scoped API key

In Workspace Settings → API Keys, create a key with a descriptive name (e.g. "Claude Ingest Agent" or "CI Verification Worker") and select only the scopes it needs. Scopes are additive and immutable after creation — revoke and recreate a key to change its scopes.

events:write        # capture events (default scope)
events:read         # list top event names
insights:read       # read saved insights, run ad-hoc queries
insights:write      # create insights
dashboards:read     # list/read dashboards
dashboards:write    # create dashboards
recordings:read     # list and stream session recordings

Every request authenticates the same way: an Authorization: Bearer analas_sk_... header (legacy analas_pk_... keys continue to be fully supported). A key can only act on the workspace it was created in, and only within the scopes it was granted — a read-only key can never create or delete anything.

2. Endpoint reference

{ "events": ["page_view", "checkout_completed", "signup"] }

{ "type": "trend", "queryConfig": { "eventName": "checkout_completed", "timeFrame": 14 } }

{ "total": 842, "rows": [{ "day": "2026-07-21", "count": 61 }] }

{ "insight": { "id": "...", "name": "...", "type": "trend", "queryConfig": {...} } }

{ "total": 842, "rows": [...] }

{ "name": "Signups / day", "type": "trend", "queryConfig": { "eventName": "signup", "timeFrame": 30 }, "dashboardId": "optional" }

{ "insight": { "id": "...", "name": "...", "type": "trend" } }

{ "dashboards": [{ "id": "...", "name": "...", "insights": [...] }] }

{ "dashboard": { "id": "...", "name": "...", "insights": [...] } }

{ "name": "Agent-built dashboard" }

{ "dashboard": { "id": "...", "name": "..." } }

{ "total": 120, "rows": [...], "nextCursor": "..." }

application/x-ndjson body

Insight type values: count, trend, breakdown, multi_trend, funnel, metric, retention, session_recording — see insight types docs for each type's queryConfig fields. Insight types beyond count and trend require a plan that includes that feature — a 403 response means an upgrade is needed, not a bug.

breakdown and trend also accept an optional filters array in queryConfig to narrow by other properties: "filters": [{ "property": "city", "value": "Tehran" }] (up to 5, each an exact-match equality check). For trend, this is how you plot two segments as separate lines on one chart — run the query twice with different filter values and combine the two rows arrays client-side. Requires a plan with the advanced_filters feature — on plans without it, filters are silently ignored and the query runs unfiltered rather than erroring.

3. Worked examples

curl https://your-domain.com/api/v1/insights/query \
  -H "Authorization: Bearer $ANALAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"count","queryConfig":{"eventName":"error_boundary_triggered"}}'

# Compare a saved insight's data before/after a deploy
curl https://your-domain.com/api/v1/insights/ins_abc123/data \
  -H "Authorization: Bearer $ANALAS_KEY"

curl https://your-domain.com/api/v1/insights/query \
  -H "Authorization: Bearer $ANALAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"breakdown","queryConfig":{"eventName":"reservation_completed","property":"city","filters":[{"property":"flow","value":"customer"}]}}'

# Run twice with different filter values, plot both "rows" arrays on one chart
curl https://your-domain.com/api/v1/insights/query \
  -H "Authorization: Bearer $ANALAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"trend","queryConfig":{"eventName":"page_view","timeFrame":14,"filters":[{"property":"entry_flow","value":"map_search"}]}}'

curl https://your-domain.com/api/v1/insights/query \
  -H "Authorization: Bearer $ANALAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"type":"trend","queryConfig":{"eventName":"page_view","timeFrame":14,"filters":[{"property":"entry_flow","value":"home"}]}}'

curl -X POST https://your-domain.com/api/v1/dashboards \
  -H "Authorization: Bearer $ANALAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Agent-built: onboarding health"}'

curl -X POST https://your-domain.com/api/v1/insights \
  -H "Authorization: Bearer $ANALAS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Signups / day","type":"trend","queryConfig":{"eventName":"signup","timeFrame":30},"dashboardId":"<id from above>"}'