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.

Rate Limiting

The analytics endpoint is rate-limited per API key. Default: 30 requests per minute. Rate limit headers are included in every response:

Header	Description
X-RateLimit-Limit	Maximum requests per window.
X-RateLimit-Remaining	Remaining requests in current window.
X-RateLimit-Reset	Unix timestamp when the window resets.
Retry-After	Seconds to wait (only on 429).

Error Responses

Status	Meaning
400	Invalid date format or unrecognized category.
401	Missing or invalid API key.
403	Key doesn’t match the project or lacks analytics:read scope.
429	Rate limit exceeded. Check Retry-After header.

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') }}