---
title: Usage Metrics
summary: These endpoints return usage metrics for requests made through <a href="https://www.fastly.com/documentation/reference/api/ai-runtime-control">AI Runtime Control</a>, including request counts, session counts, and token consumption. Metrics can be filtered by virtual key, provider, and model.
url: https://www.fastly.com/documentation/reference/api/ai-runtime-control/usage-metrics
---

These endpoints return usage metrics for requests made through <a href="https://www.fastly.com/documentation/reference/api/ai-runtime-control">AI Runtime Control</a>, including request counts, session counts, and token consumption. Metrics can be filtered by virtual key, provider, and model.

## Data model

| Field | Type | Description |
|-------|------|-------------|
| `date` | string | The date (or hour) the usage was measured. Formatted as <code>YYYY-MM-DD</code> when <code>granularity</code> is <code>daily</code>, or <code>YYYY-MM-DD HH:00:00</code> when <code>granularity</code> is <code>hourly</code>. |
| `model` | string | The AI model identifier used. |
| `primary_provider` | string | The ID of the provider connection originally requested, before any failover occurred. |
| `provider` | string | The name of the provider connection that ultimately served the request. |
| `provider_connection_id` | string | The ID of the provider connection that ultimately served the request. |
| `quantity` | integer | The quantity of the usage type for this date. |
| `usage_type` | string | The type of usage being measured. |
| `virtual_key_id` | string | The ID of the virtual key this usage is attributed to. |
| `virtual_key_name` | string | The display name of the virtual key this usage is attributed to. |
| `sort` | string | The <code>sort</code> value used when making the request. |
| `total` | integer | The count of results matching the request. |
| `meta` | object | Metadata about the request. |

## API endpoints

### Get usage metrics

**GET** `/ai-runtime-control/v1/usage-metrics`

Returns usage metrics for AI Runtime Control requests, including request counts, session counts, input token counts, and output token counts.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `from` | string | query | No | The start of the time range, in RFC 3339 format. |
| `granularity` | string | query | No | The time granularity to aggregate usage by. |
| `key` | string | query | No | Filter results to a specific virtual key ID. |
| `model` | string | query | No | Filter results by AI model identifier. |
| `provider` | string | query | No | Filter results by AI provider connection ID. |
| `sort` | string | query | No | Sort field. Prefix with <code>-</code> for descending order (e.g., <code>sort=-date</code>). |
| `to` | string | query | No | The end of the time range, in RFC 3339 format. Defaults to now. |

### Export usage metrics

**GET** `/ai-runtime-control/v1/usage-metrics/export`

Returns usage metrics for AI Runtime Control requests. Accepts the same filter
parameters as <a href="#arc-get-usage-metrics">get usage metrics</a>, except <code>sort</code> and
<code>granularity</code>, which aren't supported here.
Set the <code>Accept</code> header to <code>text/csv</code> to receive a CSV file download instead of a
JSON response. In the CSV output, the column named <code>time</code> corresponds to the <code>date</code>
field in the JSON response.

**Parameters:**

| Name | Type | In | Required | Description |
|------|------|----|---------|--------------|
| `from` | string | query | No | The start of the time range, in RFC 3339 format. |
| `key` | string | query | No | Filter results to a specific virtual key ID. |
| `model` | string | query | No | Filter results by AI model identifier. |
| `provider` | string | query | No | Filter results by AI provider connection ID. |
| `to` | string | query | No | The end of the time range, in RFC 3339 format. Defaults to now. |

