## Aggregate Usage Metrics

**get** `/api/v1/admin/usage-metrics/aggregate`

Aggregate usage metrics by one or more dimensions, reporting total credits used. Global admin only.

A date range is required, which bounds the scan via the `day`-leading index. Supplying `organization_id` narrows it further via the `(organization_id, day)` index.

Supported `group_by` dimensions: `day`, `organization_id`, `project_id`, `event_type`, `user_id`. Buckets are ordered by total credits descending.

### Query Parameters

- `day_on_or_after: string`

  Inclusive lower bound on the day (YYYY-MM-DD, UTC)

- `day_on_or_before: string`

  Inclusive upper bound on the day (YYYY-MM-DD, UTC)

- `group_by: array of string`

  Dimensions to group by: day, organization_id, project_id, event_type, user_id

- `event_types: optional array of "audio_seconds_parsed" or "chart_parsing_agentic" or "chart_parsing_efficient" or 27 more`

  Filter by event types

  - `"audio_seconds_parsed"`

  - `"chart_parsing_agentic"`

  - `"chart_parsing_efficient"`

  - `"chart_parsing_plus"`

  - `"chat_message_sent"`

  - `"confidence_score_high"`

  - `"directory_count_snapshot"`

  - `"directory_file_count_snapshot"`

  - `"directory_files_exported"`

  - `"directory_files_ingested"`

  - `"directory_pages_exported"`

  - `"extraction_num_pages"`

  - `"form_parsing_pages"`

  - `"image_classified"`

  - `"index_retrieve_query"`

  - `"layout_aware_chart_extraction"`

  - `"layout_aware_parsing"`

  - `"layout_extracted"`

  - `"pages_classified"`

  - `"pages_embedded"`

  - `"pages_indexed"`

  - `"pages_parsed"`

  - `"pages_split"`

  - `"pages_verified"`

  - `"precise_bbox_extraction"`

  - `"set_total_indexes"`

  - `"set_total_pages_indexed"`

  - `"spreadsheet_regions_extracted"`

  - `"stored_file_count"`

  - `"stored_file_mb"`

- `organization_id: optional string`

  Filter by organization ID

- `project_id: optional string`

  Filter by project ID

- `user_id: optional string`

  Filter by user ID

### Cookie Parameters

- `session: optional string`

### Returns

- `buckets: array of object { dimensions, metric_count, total_credits, total_value }`

  The aggregation buckets, ordered by total credits descending

  - `dimensions: map[string]`

    The dimension values that define this bucket

  - `metric_count: number`

    Number of metric rows in this bucket

  - `total_credits: number or string`

    Total credits consumed by metrics in this bucket

    - `number`

    - `string`

  - `total_value: number`

    Total of the metric `value` field in this bucket

- `group_by: array of "day" or "event_type" or "organization_id" or 2 more`

  The dimensions the metrics were grouped by

  - `"day"`

  - `"event_type"`

  - `"organization_id"`

  - `"project_id"`

  - `"user_id"`

### Example

```http
curl https://api.cloud.llamaindex.ai/api/v1/admin/usage-metrics/aggregate \
    -H "Authorization: Bearer $LLAMA_CLOUD_API_KEY"
```

#### Response

```json
{
  "buckets": [
    {
      "dimensions": {
        "foo": "string"
      },
      "metric_count": 0,
      "total_credits": 0,
      "total_value": 0
    }
  ],
  "group_by": [
    "day"
  ]
}
```