# 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.

<Mermaid chart={`flowchart TD
    A[Assistant Interaction] --> B[Raw Event Storage]
    B --> C[Metrics Aggregation]
    C --> D["/v1/metrics/:metric"]
    C --> E["/v1/metrics/bulkAll"]

    D --> G[Time-series Data]
    E --> H[Bulk Aggregated Data]`} />

| 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.

```http
GET /v1/metrics/duration?from=2026-03-10T00:00:00Z&to=2026-03-12T00:00:00Z
Authorization: Bearer your-api-key-here
```

:::warning{title="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/:metric

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**

```http
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:**

```json
[
  {
    "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:**

| 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**

```http
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):**

```json
[
  {
    "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**

```http
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`.

| Key           | Description                               | Example Values                           |
| ------------- | ----------------------------------------- | ---------------------------------------- |
| `assistantId` | Assistant identifier | `"d66f9abb-52d9-4547-ab51-45d27868f949"` |

<br />

***

## 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` |

:::warning{title="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.
