Fetching metrics
Use the legacy v1 Metrics API to query conversation counts, duration, token usage, and fixed-rate cost estimates across your Organisations and Projects.
Paths below are relative to the Metrics service, for example https://newprd.reecall.io/metrics. The v1 pricing field uses fixed rates and is an estimate, independent of the actual models used. For recorded costs derived from priced usage rows, use /v2/billing or /v2/billing/traces.
Overview
The Metrics API aggregates events from Assistant conversations. Query a single metric in time buckets or retrieve totals for multiple metrics over the same period.
| Endpoint | Purpose | Use Case |
|---|---|---|
/v1/metrics/:metric | Single metric over time | Dashboards, trend analysis |
/v1/metrics/bulkAll | Multiple metrics aggregated | Cost calculations, reporting |
Authentication
The v1 endpoints in this guide require an organization-scoped API key or an account with equivalent permissions. Project-scoped API keys do not have access to these v1 routes.
Code
Scope-based Access
Your key's organization scope overrides organizationId. Use projectId to narrow the query to one Project in that Organization.
Available metrics
| Metric Name | Description |
|---|---|
exchangeCount | Number of conversation exchanges |
duration | Total conversation duration (seconds) |
indivisibleDuration | Indivisible duration blocks (minutes) |
usage.stt.audioDuration | Speech-to-text audio duration in seconds |
usage.tts.characters | Text-to-speech character count |
usage.conversational.inputTextTokens | Input tokens for conversational AI |
usage.conversational.outputTextTokens | Output tokens for conversational AI |
usage.conversational.cachedTextTokens | Cached tokens for conversational AI |
usage.realtime.inputTextTokens | Input tokens for realtime AI |
usage.realtime.outputTextTokens | Output tokens for realtime AI |
usage.realtime.inputAudioTokens | Input audio tokens for realtime AI |
usage.realtime.outputAudioTokens | Output audio tokens for realtime AI |
usage.realtime.cachedTextTokens | Cached text tokens for realtime AI |
usage.realtime.cachedAudioTokens | Cached audio tokens for realtime AI |
usage.postProcessing.inputTextTokens | Input tokens for post-processing |
usage.postProcessing.outputTextTokens | Output tokens for post-processing |
usage.postProcessing.cachedTextTokens | Cached tokens for post-processing |
The API also accepts usage.conversational.totalTextTokens, usage.realtime.totalTextTokens, usage.realtime.totalAudioTokens, and usage.postProcessing.totalTextTokens. In conversation summaries, these totals mean input tokens including cached tokens; output tokens are reported separately.
Fetching time-series metrics
GET /v1/metrics/
Retrieve aggregated data for a single metric over a specified time range, bucketed by granularity.
Query Parameters:
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
from | string | Yes | Start time (inclusive). ISO 8601 format | |
to | string | Yes | End time (inclusive). ISO 8601 format | |
granularity | string | No | hour | Time bucket size: hour, day, week, month, year, all |
padMissing | string | No | false | Fill gaps with zero values when "true" |
projectId | string | No | Filter by Project ID | |
traceId | string | No | Filter by trace ID (UUID) | |
context | string | No | JSON object for context filtering |
Example: Daily conversation duration over a two-day interval, including the end boundary
Code
Response:
Code
Response Fields:
| Field | Type | Description |
|---|---|---|
timestamp | string | ISO 8601 timestamp marking the bucket start |
data.sum | number | Total value across all events in the bucket |
data.avg | number | Average value per event in the bucket |
data.min | number | Minimum value in the bucket |
data.max | number | Maximum value in the bucket |
data.count | number | Number of events in the bucket |
pricing | number | Optional fixed-rate estimate in EUR; omitted for metrics without a calculator |
Examples use illustrative aggregates, with rounded averages and prices rounded to six decimal places.
Fetching multiple metrics
GET /v1/metrics/bulkAll
Retrieve aggregated data for multiple metrics over the entire time range as single values.
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
metrics | string | Yes | Comma-separated list of metric names |
from | string | Yes | Start time (inclusive). ISO 8601 format |
to | string | Yes | End time (inclusive). ISO 8601 format |
organizationId | string | No | Filter by Organisation ID |
projectId | string | No | Filter by Project ID |
traceId | string | No | Filter by trace ID (UUID) |
context | string | No | JSON object for context filtering |
Example: Fixed-rate usage estimates for the past month
Code
Response excerpt (two of the four requested metrics):
Code
Context filtering
Use the context parameter to filter events by specific criteria. The value must be a JSON-encoded object where each key matches exactly.
Example: Filter by Assistant
Code
Context filters match fields actually recorded in each summary event; arbitrary keys are not populated automatically. assistantId identifies the initial Assistant that owns the conversation summary, even if the call transfers to another Assistant. Other recorded fields include conversationId and mode.
| Key | Description | Example Values |
|---|---|---|
assistantId | Assistant identifier | "d66f9abb-52d9-4547-ab51-45d27868f949" |
Limitations
| Constraint | Limit | Description |
|---|---|---|
| Granularity intervals | 50 | Maximum calculated intervals in the requested range |
| Date range validation | Required | from must be before to |
| Bulk metrics | All available | No limit on metric count for /v1/metrics/bulkAll |
Interval Limit
When using granular time buckets, ensure your date range doesn't exceed 50 intervals. Because to is inclusive, padding also includes a bucket starting exactly at to when it falls on a bucket boundary. For example, querying 51 days with granularity=day will be rejected. Use a wider granularity or narrow your date range.
Best practices
Optimising query performance
- Use
granularity=allfor simple totals rather than fine-grained time series - Use
/v1/metrics/bulkAllwhen you need multiple metrics for the same time range - Apply
projectIdfilters to reduce data volume - Use
contextfiltering to focus on specific use cases
Cost monitoring workflows
- Query
durationand token usage together to inspect consumption; use v2 billing endpoints for recorded costs - Use daily or weekly granularity for trend analysis dashboards
- Implement alerts by comparing current usage against historical baselines
- Use
exchangeCountto count matching conversation summary events. For a metric's owndata.count, only summary events that contain that metric are counted.