Skip to content
LlamaCloud Admin API
Product Docs
API Reference
Admin
Usage Metrics

Aggregate Usage Metrics

admin.usage_metrics.aggregate(UsageMetricAggregateParams**kwargs) -> UsageMetricAggregateResponse
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.

ParametersExpand Collapse
day_on_or_after: str

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

day_on_or_before: str

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

group_by: Sequence[str]

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

event_types: Optional[List[Literal["audio_seconds_parsed", "chart_parsing_agentic", "chart_parsing_efficient", 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[str]

Filter by organization ID

project_id: Optional[str]

Filter by project ID

user_id: Optional[str]

Filter by user ID

ReturnsExpand Collapse
class UsageMetricAggregateResponse: …

Response containing usage metrics aggregated by one or more dimensions.

buckets: List[Bucket]

The aggregation buckets, ordered by total credits descending

dimensions: Dict[str, str]

The dimension values that define this bucket

metric_count: int

Number of metric rows in this bucket

total_credits: Union[float, str]

Total credits consumed by metrics in this bucket

One of the following:
float
str
total_value: int

Total of the metric value field in this bucket

group_by: List[Literal["day", "event_type", "organization_id", 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

import os
from llama_cloud_admin import LlamaCloudAdmin

client = LlamaCloudAdmin(
    api_key=os.environ.get("LLAMA_CLOUD_API_KEY"),  # This is the default and can be omitted
)
response = client.admin.usage_metrics.aggregate(
    day_on_or_after="day_on_or_after",
    day_on_or_before="day_on_or_before",
    group_by=["string"],
)
print(response.buckets)
{
  "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"
  ]
}