# Fetch metrics for an Assistant

Filter `/v1/metrics/bulkAll` by `context.assistantId` to retrieve an Assistant's aggregated usage and fixed-rate cost estimates.

***

Use an organization-scoped API key for this v1 endpoint. Project-scoped keys cannot access it. The `pricing` values use legacy fixed rates. For recorded Assistant costs, use `/metrics/v2/billing/assistants/<assistant-id>`.

## Endpoint

```
GET https://newprd.reecall.io/metrics/v1/metrics/bulkAll
```

***

## Use case: fetch consumption for a single Assistant

### Goal

Use the initial Assistant's ID in the `context` filter. Conversation summaries belong to the Assistant that answered the call, including when the call transfers to another Assistant.

### Request

```bash
curl --location 'https://newprd.reecall.io/metrics/v1/metrics/bulkAll?from=2026-03-10T08:00:00.000Z&to=2026-03-20T08:00:00.000Z&context=%7B%22assistantId%22%3A%22d66f9abb-52d9-4547-ab51-45d27868f949%22%7D&metrics=duration,indivisibleDuration,usage.tts.characters,usage.conversational.inputTextTokens,usage.conversational.outputTextTokens,usage.conversational.cachedTextTokens' \
--header 'Authorization: Bearer <YOUR_API_KEY>'
```

> The `context` parameter is URL-encoded. The decoded value is:
>
> ```json
> {"assistantId":"d66f9abb-52d9-4547-ab51-45d27868f949"}
> ```

### Query parameters

| Parameter | Value                                                    | Description                                  |
| --------- | -------------------------------------------------------- | -------------------------------------------- |
| `from`    | `2026-03-10T08:00:00.000Z`                               | Start of the time window (ISO 8601)          |
| `to`      | `2026-03-20T08:00:00.000Z`                               | End of the time window (ISO 8601)            |
| `context` | `{"assistantId":"d66f9abb-52d9-4547-ab51-45d27868f949"}` | JSON object filtering events by Assistant ID |
| `metrics` | See below                                                | Comma-separated list of metrics to retrieve  |

### Metrics requested

| Metric                                  | Description                                     |
| --------------------------------------- | ----------------------------------------------- |
| `duration`                              | Total conversation duration (seconds)           |
| `indivisibleDuration`                   | Billed duration blocks (minutes)                |
| `usage.tts.characters`                  | Characters sent to text-to-speech               |
| `usage.conversational.inputTextTokens`  | Input tokens consumed by the conversational AI  |
| `usage.conversational.outputTextTokens` | Output tokens produced by the conversational AI |
| `usage.conversational.cachedTextTokens` | Cached tokens reused by the conversational AI   |

***

## Example response

These aggregates are illustrative, with rounded averages and prices rounded to six decimal places.

```json
[
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 9420.5,
      "avg": 94.2,
      "min": 18.3,
      "max": 210.7,
      "count": 100
    },
    "pricing": 1.570083,
    "metric": "duration"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 210,
      "avg": 2.1,
      "min": 1,
      "max": 4,
      "count": 100
    },
    "pricing": 10.08,
    "metric": "indivisibleDuration"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 187400,
      "avg": 1874,
      "min": 120,
      "max": 4850,
      "count": 100
    },
    "pricing": 17.637647,
    "metric": "usage.tts.characters"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 512300,
      "avg": 5123,
      "min": 340,
      "max": 14200,
      "count": 100
    },
    "pricing": 0.210043,
    "metric": "usage.conversational.inputTextTokens"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 68900,
      "avg": 689,
      "min": 45,
      "max": 1920,
      "count": 100
    },
    "pricing": 0.175006,
    "metric": "usage.conversational.outputTextTokens"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 24100,
      "avg": 241,
      "min": 0,
      "max": 980,
      "count": 100
    },
    "pricing": 0.00241,
    "metric": "usage.conversational.cachedTextTokens"
  }
]
```

***

## Reading the response

Each object corresponds to one metric, aggregated across matching conversation summaries owned by this Assistant within the time window. The `count` reflects summary events containing that metric; it is not a count of model requests or handoffs.

| Field        | Type   | Description                                                     |
| ------------ | ------ | --------------------------------------------------------------- |
| `timestamp`  | string | Start of the aggregation window (matches `from`)                |
| `metric`     | string | Name of the metric                                              |
| `data.sum`   | number | Total value across all conversations for this Assistant         |
| `data.avg`   | number | Average value per conversation                                  |
| `data.min`   | number | Lowest value recorded in a single conversation                  |
| `data.max`   | number | Highest value recorded in a single conversation                 |
| `data.count` | number | Number of matching summary events containing this metric    |
| `pricing`    | number | Estimated cost in EUR for this metric over the full time window |

***

## Difference vs. the traceId use case

| Dimension          | `traceId` filter              | `context.assistantId` filter                  |
| ------------------ | ----------------------------- | --------------------------------------------- |
| Scope              | Single conversation           | Summaries owned by the initial Assistant           |
| `data.count`       | Normally `1` when a matching summary contains the metric                    | N conversations in the time window            |
| `data.avg/min/max` | Identical to `sum` for one matching event            | Reflects the spread across matching summary events |
| Typical use        | Inspect one call's usage | Monitor usage attributed to the initial Assistant       |

***

## Notes

* The `context` parameter must be a valid JSON object, URL-encoded in the query string.
* `assistantId` is a recorded context field whose value is the UUID of the initial Assistant. Filters can also match other recorded context fields, such as `conversationId` or `mode`.
* Combine with `projectId` to scope results further to a specific project within an organisation.
* Summing the `pricing` values gives a fixed-rate estimate for the selected metrics. It does not give recorded billing costs.
* `from` must be before `to`. `bulkAll` uses `granularity=all` and returns one row per requested metric, including a zero row when no data matches.
* Your organization scope is applied automatically; `projectId` can narrow the query within that Organization.

***

## Related endpoints

| Endpoint              | When to use                                                              |
| --------------------- | ------------------------------------------------------------------------ |
| `/v1/metrics/bulkAll` | Retrieve multiple metrics aggregated over the full time window           |
| `/v1/metrics/:metric` | Retrieve one metric as a time series (hourly, daily…) for this Assistant |
