# Usage Metrics

## Aggregate Usage Metrics

`client.admin.usageMetrics.aggregate(UsageMetricAggregateParamsquery, RequestOptionsoptions?): 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

- `query: UsageMetricAggregateParams`

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

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

  - `event_types?: Array<"audio_seconds_parsed" | "chart_parsing_agentic" | "chart_parsing_efficient" | 27 more> | null`

    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?: string | null`

    Filter by organization ID

  - `project_id?: string | null`

    Filter by project ID

  - `user_id?: string | null`

    Filter by user ID

### Returns

- `UsageMetricAggregateResponse`

  Response containing usage metrics aggregated by one or more dimensions.

  - `buckets: Array<Bucket>`

    The aggregation buckets, ordered by total credits descending

    - `dimensions: Record<string, string>`

      The dimension values that define this bucket

    - `metric_count: number`

      Number of metric rows in this bucket

    - `total_credits: number | 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<"day" | "event_type" | "organization_id" | 2 more>`

    The dimensions the metrics were grouped by

    - `"day"`

    - `"event_type"`

    - `"organization_id"`

    - `"project_id"`

    - `"user_id"`

### Example

```typescript
import LlamaCloudAdmin from '@llamaindex/llama-cloud-admin';

const client = new LlamaCloudAdmin({
  apiKey: process.env['LLAMA_CLOUD_API_KEY'], // This is the default and can be omitted
});

const response = await client.admin.usageMetrics.aggregate({
  day_on_or_after: 'day_on_or_after',
  day_on_or_before: 'day_on_or_before',
  group_by: ['string'],
});

console.log(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

- `UsageMetricAggregateResponse`

  Response containing usage metrics aggregated by one or more dimensions.

  - `buckets: Array<Bucket>`

    The aggregation buckets, ordered by total credits descending

    - `dimensions: Record<string, string>`

      The dimension values that define this bucket

    - `metric_count: number`

      Number of metric rows in this bucket

    - `total_credits: number | 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<"day" | "event_type" | "organization_id" | 2 more>`

    The dimensions the metrics were grouped by

    - `"day"`

    - `"event_type"`

    - `"organization_id"`

    - `"project_id"`

    - `"user_id"`