---
title: "Aggregate Usage Metrics"
method: GET
path: "/api/v1/beta/usage-metrics/aggregate"
tags: ["Beta", "Usage Metrics"]
---

# Aggregate Usage Metrics

`GET /api/v1/beta/usage-metrics/aggregate`

## Request

- Base URL: `https://api.cloud.llamaindex.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.cloud.llamaindex.ai/api/v1/beta/usage-metrics/aggregate`
- Auth: HTTP bearer

Aggregate usage metrics using the same filters as the regular list endpoint.

The authenticated organization is always applied as a filter.

## Query parameters

- `group_by` string[], required: Dimensions to group by: day, project_id, event_type, tier.
- `organization_id` string, uuid, required
- `project_id` string, uuid, nullable: Filter by project ID
- `user_id` string, nullable: Filter by user ID
- `event_types` string[], nullable: Filter by event types
- `days` string[], nullable: Filter by specific days (YYYY-MM-DD)
- `day_on_or_before` string, nullable: Filter by days on or before this date (YYYY-MM-DD)
- `day_on_or_after` string, nullable: Filter by days on or after this date (YYYY-MM-DD)
- `event_aggregation_type` string, nullable: Filter by event aggregation type
- `event_aggregation_key` string, nullable: Filter by event aggregation key
- `credits_consumed_greater_than_or_equal` number, nullable: Filter by credits consumed greater than or equal to this value

## Cookies

- `session` string, nullable

## Response `200`

Successful Response

- UsageMetricAggregateResponse: Usage metrics aggregated by the requested dimensions.
  - `group_by` string[], required: Dimensions used to group metrics
  - `buckets` UsageMetricAggregateBucket[], required: Aggregated metric groups
    - `dimensions` object, required: Values defining this group
    - `total_credits` number, required: Credits consumed in this group
    - `total_value` integer, required: Metric units in this group
    - `metric_count` integer, required: Usage records in this group

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `a38b684f8e1b`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/run-llama/apis/llama-platform/changes/api/v1/beta/usage-metrics/aggregate/get.md)

---

[API](https://skmtc.dev/run-llama/apis/llama-platform.md) · [All operations](https://skmtc.dev/run-llama/apis/llama-platform/llms.txt) · [OpenAPI document](https://skmtc.dev/run-llama/apis/llama-platform/revisions/809d302cdb1e?raw)