# 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.

### Parameters

- `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

  - `"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

### Returns

- `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

      - `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

    - `"day"`

    - `"event_type"`

    - `"organization_id"`

    - `"project_id"`

    - `"user_id"`

### Example

```python
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)
```

#### Response

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

## Domain Types

### Usage Metric Aggregate Response

- `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

      - `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

    - `"day"`

    - `"event_type"`

    - `"organization_id"`

    - `"project_id"`

    - `"user_id"`