Insights API

Retrieve the conversation insights that power your dashboard’s Insights tab: sentiment, resolution and escalation rates, top topics, tone, and per-day trends. Two endpoints are available:

• GET /insights — deterministic metrics and trends for a date range. No AI cost, fast, ideal for dashboards and scheduled reports.
• POST /insights/query — ask a natural-language question and get a written answer grounded in those same metrics.

Both require an API key with the insights:read scope. See API Keys to create one.

Note

For privacy, neither endpoint returns individual conversation transcripts or summaries. Only aggregate metrics and trends are exposed.

Metrics endpoint

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

Query Parameters

Parameter	Type	Default	Description
from	string	30 days ago	Start date (YYYY-MM-DD), inclusive.
to	string	Today	End date (YYYY-MM-DD), inclusive.
deviceId	string	—	Limit metrics to a single device/kiosk by its slug (e.g. lobby-kiosk).
compare	string	—	Compare against another device slug, or __rest__ for every other device. Requires deviceId. Returns a comparison block.
compareToPrevious	boolean	false	When true, also returns metrics for the immediately-preceding period as previousMetrics. Ignored when compare is set.

Response Format

{
  "projectId": "proj-uuid-...",
  "range": { "from": "2026-03-01", "to": "2026-03-25" },
  "compareToPrevious": false,
  "metrics": {
    "conversationCount": 184,
    "avgSentiment": 0.42,
    "sentimentBreakdown": { "positive": 96, "neutral": 61, "negative": 27 },
    "resolutionRate": 0.78,
    "escalationRate": 0.09,
    "unansweredRate": 0.05,
    "topTopics": [
      { "topic": "billing", "count": 45, "share": 0.245 },
      { "topic": "opening hours", "count": 31, "share": 0.168 }
    ],
    "toneDistribution": { "polite": 0.71, "frustrated": 0.18, "formal": 0.4 }
  },
  "previousMetrics": null,
  "trend": [
    {
      "date": "2026-03-24",
      "conversationCount": 12,
      "avgSentiment": 0.38,
      "resolved": 9,
      "escalated": 1,
      "unanswered": 1
    }
  ],
  "comparison": null,
  "compatibility": {
    "currentProvider": "openai",
    "currentModel": "text-embedding-3-small",
    "compatibleCount": 184,
    "incompatibleCount": 0,
    "missingCount": 0,
    "staleModels": []
  },
  "notices": []
}

Metric Fields

Field	Description
conversationCount	Number of analyzed conversations in the period.
avgSentiment	Average sentiment score from -1 (negative) to 1 (positive), or null when no data.
sentimentBreakdown	Conversation counts grouped by sentiment label.
resolutionRate	Share of conversations where the user’s need was met (0–1), or null when unknown.
escalationRate	Share of conversations handed off to a human (0–1), or null when unknown.
unansweredRate	Share of conversations the assistant could not answer (0–1), or null when unknown.
topTopics	Up to 10 topics with their count and share (fraction of conversations).
toneDistribution	Average value (0–1) for each detected tone dimension.
trend	Per-day series (gap-filled) of counts, average sentiment, and outcome tallies.
comparison	When compare is set: the same metrics and trend for the comparison scope.
compatibility	Embedding-model coverage for analyzed conversations. See note below.
notices	Human-readable warnings, e.g. when some conversations were analyzed with an older embedding model.

Note

compatibility reports how many analyzed conversations were embedded with your organization’s current embedding model. Conversations embedded with a previous model are excluded from semantic matching until re-analyzed, and a message is added to notices.

Question endpoint

Ask a natural-language question. The answer is generated from the same deterministic metrics above — figures are never invented.

curl -X POST "https://your-ragtime-instance.com/api/v1/projects/{projectId}/insights/query" \
  -H "Authorization: Bearer rt_live_YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How did customer sentiment change this month?",
    "from": "2026-03-01",
    "to": "2026-03-25",
    "compareToPrevious": true
  }'

Request Body

Field	Type	Default	Description
question	string	—	Required. The question to answer (max 500 characters).
from	string	30 days ago	Start date (YYYY-MM-DD), inclusive.
to	string	Today	End date (YYYY-MM-DD), inclusive.
deviceId	string	—	Limit analysis to a single device/kiosk by its slug.
compare	string	—	Compare against another device slug, or __rest__ for every other device. Requires deviceId.
compareToPrevious	boolean	false	Include the immediately-preceding period for comparison. Ignored when compare is set.

Response Format

{
  "projectId": "proj-uuid-...",
  "question": "How did customer sentiment change this month?",
  "range": { "from": "2026-03-01", "to": "2026-03-25" },
  "compareToPrevious": true,
  "answer": "Sentiment improved over the period, rising from an average of 0.31 to 0.42. Resolution stayed strong at 78%, while escalations held steady around 9%.",
  "relevantMetrics": [
    { "key": "sentiment", "phrase": "Average sentiment rose from 0.31 to 0.42." },
    { "key": "outcomes", "phrase": "Resolution held at 78% with low escalation." }
  ],
  "metrics": { "...": "same shape as the metrics endpoint" },
  "previousMetrics": { "...": "metrics for the preceding period, or null" },
  "trend": [{ "...": "per-day series" }],
  "comparison": null,
  "compatibility": { "...": "embedding coverage" },
  "notices": []
}

The answer is a written summary; relevantMetrics highlights the metrics most relevant to the question. The metrics, previousMetrics, trend, comparison, compatibility, and notices fields match the metrics endpoint.

Rate Limiting

Both endpoints are 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, missing question, or question too long.
401	Missing or invalid API key.
403	Key doesn’t match the project or lacks insights:read scope.
404	A referenced device (deviceId or compare) was not found.
429	Rate limit exceeded. Check Retry-After header.

Using with N8N

Use an HTTP Request node to pull weekly insights into Slack digests, spreadsheets, or BI tools:

// N8N HTTP Request node configuration:
// Method: GET
// URL: https://your-ragtime-instance.com/api/v1/projects/{projectId}/insights
// 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') }}
//   compareToPrevious: true