# Fetch conversation metrics

Filter `/v1/metrics/bulkAll` by a conversation's `traceId` to retrieve its duration, token usage, TTS character count, and fixed-rate cost estimates.

***

Use an organization-scoped API key for this v1 endpoint. Project-scoped API keys cannot access it. The `pricing` values are legacy fixed-rate estimates. For recorded costs for a trace, use `/metrics/v2/billing/traces?traceIds=<trace-id>`.

## Endpoint

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

***

## Use case: fetch consumption for a single conversation

### Goal

Get the `traceId` from the Exchange record. Use a time window that includes the conversation summary, which is normally emitted during call finalization.

### 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&traceId=b8c31b19-ed4b-46bb-ba48-88d20c49b64d&metrics=duration,indivisibleDuration,usage.tts.characters,usage.conversational.inputTextTokens,usage.conversational.outputTextTokens,usage.conversational.cachedTextTokens' \
--header 'Authorization: Bearer <YOUR_API_KEY>'
```

### 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)           |
| `traceId` | `b8c31b19-ed4b-46bb-ba48-88d20c49b64d` | `traceId` from the Exchange record, not its `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 prices rounded to six decimal places.

```json
[
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 87.4,
      "avg": 87.4,
      "min": 87.4,
      "max": 87.4,
      "count": 1
    },
    "pricing": 0.014567,
    "metric": "duration"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 2,
      "avg": 2,
      "min": 2,
      "max": 2,
      "count": 1
    },
    "pricing": 0.096,
    "metric": "indivisibleDuration"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 1240,
      "avg": 1240,
      "min": 1240,
      "max": 1240,
      "count": 1
    },
    "pricing": 0.116706,
    "metric": "usage.tts.characters"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 3820,
      "avg": 3820,
      "min": 3820,
      "max": 3820,
      "count": 1
    },
    "pricing": 0.001566,
    "metric": "usage.conversational.inputTextTokens"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 512,
      "avg": 512,
      "min": 512,
      "max": 512,
      "count": 1
    },
    "pricing": 0.0013,
    "metric": "usage.conversational.outputTextTokens"
  },
  {
    "timestamp": "2026-03-10T08:00:00.000Z",
    "data": {
      "sum": 0,
      "avg": 0,
      "min": 0,
      "max": 0,
      "count": 1
    },
    "pricing": 0.0,
    "metric": "usage.conversational.cachedTextTokens"
  }
]
```

***

## Reading the response

Each object in the array corresponds to one metric. With one matching conversation summary containing the requested metric, `count` is `1` and `sum`, `avg`, `min`, and `max` are identical. If no matching summary contains that metric, the endpoint returns zeros.

| Field        | Type   | Description                                             |
| ------------ | ------ | ------------------------------------------------------- |
| `timestamp`  | string | Start of the aggregation window (matches `from`)        |
| `metric`     | string | Name of the metric                                      |
| `data.sum`   | number | Total value for this conversation                       |
| `data.count` | number | Number of matching summary events containing this metric |
| `pricing`    | number | Estimated cost in EUR for this metric                   |

***

## Notes

* The `from`/`to` window must contain the time the conversation summary was emitted, normally during call finalization; otherwise the response returns `count: 0`.
* The `traceId` is a UUID assigned to each conversation by the Reecall platform.
* The `bulkAll` endpoint has no limit on the number of metrics requested and returns all as a flat array.
* Your organization scope is applied automatically. Optionally pass `projectId` to narrow the query to a Project within that Organization.
* The `pricing` field is a fixed-rate estimate in EUR for each requested metric. Summing these values gives an estimate for those metrics, not the recorded total conversation cost.
