Analytics API

Retrieve pre-aggregated daily analytics for your assistant. Use this to build custom dashboards, pipe data into BI tools, or trigger N8N workflows based on usage patterns.

Endpoint

curl "https://your-ragtime-instance.com/api/v1/projects/{projectId}/analytics?from=2026-03-01&to=2026-03-25&category=usage" \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE"

Query Parameters

Parameter	Type	Default	Description
from	string	30 days ago	Start date (YYYY-MM-DD).
to	string	Today	End date (YYYY-MM-DD), inclusive.
category	string	all	Filter to a single category (see table below).
live	boolean	true	When true, returns only live traffic. Set to false to include test/preview traffic.
deviceId	string	—	Filter analytics to a specific device/kiosk by its slug (e.g. lobby-kiosk). When set, stats are computed from raw event logs instead of daily aggregates.

Available Categories

Category	Description
usage	Message counts by user type (public, logged_in).
source	Most‑cited knowledge sources (key = source ID). Source names are included in the sources array.
action	Action button clicks by action slug.
language	Conversation language distribution.
country	User country based on IP geolocation.
device	Device type breakdown (desktop, mobile, tablet).
rag	RAG retrieval stats (hit, miss).
conversation	Conversation metrics (total, avg_messages).
session	Session counts and durations.

Response Format

{
  "projectId": "proj-uuid-...",
  "range": { "from": "2026-03-01", "to": "2026-03-25" },
  "category": "usage",
  "liveOnly": true,
  "stats": [
    { "date": "2026-03-25", "category": "usage", "key": "public", "value": 142, "isLive": true },
    { "date": "2026-03-25", "category": "usage", "key": "logged_in", "value": 38, "isLive": true },
    { "date": "2026-03-24", "category": "usage", "key": "public", "value": 129, "isLive": true }
  ],
  "sources": []
}

When the source category is included, the sources array maps source IDs (used as key in stats) to human-readable names.

Errors

Errors use the standard v1 shape, with a stable code:

{
  "code": "not_found",
  "error": "Device not found.",
  "retryable": false,
  "hint": "`deviceId` takes the device slug, not its UUID."
}

Status	Code	Meaning
400	invalid_request	Invalid date format, unrecognized category, or invalid live. error names the parameter.
404	not_found	No device with that deviceId slug in the project.

Authentication, scope and project refusals (401, 403) work the same on every endpoint; see Errors. This endpoint needs the analytics:read scope. Like every v1 endpoint it is rate limited per key and returns X-RateLimit-* headers on every response; see Rate limits.

Using with N8N

Use an HTTP Request node to fetch analytics and feed them into dashboards, Slack alerts, or spreadsheets:

// N8N HTTP Request node configuration:
// Method: GET
// URL: https://your-ragtime-instance.com/api/v1/projects/{projectId}/analytics
// Authentication: Header Auth
//   Header Name: Authorization
//   Header Value: Bearer rt_live_YOUR_KEY_HERE
// Query Params:
//   from: {{ $now.minus(7, 'days').format('yyyy-MM-dd') }}
//   to:   {{ $now.format('yyyy-MM-dd') }}