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 ParametersExpand Collapse

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

One of the following:

"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 ParametersExpand Collapse

session: optional string

ReturnsExpand Collapse

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

One of the following:

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

One of the following:

"day"

"event_type"

"organization_id"

"project_id"

"user_id"

Aggregate Usage Metrics

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

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

Returns Examples

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