Reecall
Metrics

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.

EndpointPurposeUse Case
/v1/metrics/:metricSingle metric over timeDashboards, trend analysis
/v1/metrics/bulkAllMultiple metrics aggregatedCost 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
GET /v1/metrics/duration?from=2026-03-10T00:00:00Z&to=2026-03-12T00:00:00Z Authorization: Bearer your-api-key-here

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 NameDescription
exchangeCountNumber of conversation exchanges
durationTotal conversation duration (seconds)
indivisibleDurationIndivisible duration blocks (minutes)
usage.stt.audioDurationSpeech-to-text audio duration in seconds
usage.tts.charactersText-to-speech character count
usage.conversational.inputTextTokensInput tokens for conversational AI
usage.conversational.outputTextTokensOutput tokens for conversational AI
usage.conversational.cachedTextTokensCached tokens for conversational AI
usage.realtime.inputTextTokensInput tokens for realtime AI
usage.realtime.outputTextTokensOutput tokens for realtime AI
usage.realtime.inputAudioTokensInput audio tokens for realtime AI
usage.realtime.outputAudioTokensOutput audio tokens for realtime AI
usage.realtime.cachedTextTokensCached text tokens for realtime AI
usage.realtime.cachedAudioTokensCached audio tokens for realtime AI
usage.postProcessing.inputTextTokensInput tokens for post-processing
usage.postProcessing.outputTextTokensOutput tokens for post-processing
usage.postProcessing.cachedTextTokensCached 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:

ParameterTypeRequiredDefaultDescription
fromstringYesStart time (inclusive). ISO 8601 format
tostringYesEnd time (inclusive). ISO 8601 format
granularitystringNohourTime bucket size: hour, day, week, month, year, all
padMissingstringNofalseFill gaps with zero values when "true"
projectIdstringNoFilter by Project ID
traceIdstringNoFilter by trace ID (UUID)
contextstringNoJSON object for context filtering

Example: Daily conversation duration over a two-day interval, including the end boundary

Code
GET /v1/metrics/duration?from=2026-03-10T00:00:00Z&to=2026-03-12T00:00:00Z&granularity=day&padMissing=true Authorization: Bearer your-api-key-here

Response:

JSONCode
[ { "timestamp": "2026-03-10T00:00:00.000Z", "data": { "sum": 1847.5, "avg": 92.375, "min": 15.2, "max": 180.7, "count": 20 }, "pricing": 0.307917 }, { "timestamp": "2026-03-11T00:00:00.000Z", "data": { "sum": 0, "avg": 0, "min": 0, "max": 0, "count": 0 }, "pricing": 0.0 }, { "timestamp": "2026-03-12T00:00:00.000Z", "data": { "sum": 0, "avg": 0, "min": 0, "max": 0, "count": 0 }, "pricing": 0.0 } ]

Response Fields:

FieldTypeDescription
timestampstringISO 8601 timestamp marking the bucket start
data.sumnumberTotal value across all events in the bucket
data.avgnumberAverage value per event in the bucket
data.minnumberMinimum value in the bucket
data.maxnumberMaximum value in the bucket
data.countnumberNumber of events in the bucket
pricingnumberOptional 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:

ParameterTypeRequiredDescription
metricsstringYesComma-separated list of metric names
fromstringYesStart time (inclusive). ISO 8601 format
tostringYesEnd time (inclusive). ISO 8601 format
organizationIdstringNoFilter by Organisation ID
projectIdstringNoFilter by Project ID
traceIdstringNoFilter by trace ID (UUID)
contextstringNoJSON object for context filtering

Example: Fixed-rate usage estimates for the past month

Code
GET /v1/metrics/bulkAll?metrics=duration,usage.conversational.inputTextTokens,usage.conversational.outputTextTokens,usage.tts.characters&from=2026-02-17T00:00:00Z&to=2026-03-17T00:00:00Z Authorization: Bearer your-api-key-here

Response excerpt (two of the four requested metrics):

JSONCode
[ { "timestamp": "2026-02-17T00:00:00.000Z", "data": { "sum": 45230.8, "avg": 89.2, "min": 12.5, "max": 245.7, "count": 507 }, "pricing": 7.538467, "metric": "duration" }, { "timestamp": "2026-02-17T00:00:00.000Z", "data": { "sum": 2847392, "avg": 5618.3, "min": 45, "max": 12847, "count": 507 }, "pricing": 1.167431, "metric": "usage.conversational.inputTextTokens" } ]

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
GET /v1/metrics/duration?from=2026-03-01T00:00:00Z&to=2026-03-17T00:00:00Z&granularity=day&context=%7B%22assistantId%22%3A%22d66f9abb-52d9-4547-ab51-45d27868f949%22%7D Authorization: Bearer your-api-key-here

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.

KeyDescriptionExample Values
assistantIdAssistant identifier"d66f9abb-52d9-4547-ab51-45d27868f949"


Limitations

ConstraintLimitDescription
Granularity intervals50Maximum calculated intervals in the requested range
Date range validationRequiredfrom must be before to
Bulk metricsAll availableNo 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=all for simple totals rather than fine-grained time series
  • Use /v1/metrics/bulkAll when you need multiple metrics for the same time range
  • Apply projectId filters to reduce data volume
  • Use context filtering to focus on specific use cases

Cost monitoring workflows

  • Query duration and 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 exchangeCount to count matching conversation summary events. For a metric's own data.count, only summary events that contain that metric are counted.
Last modified on