# Usage Metrics

## Aggregate Usage Metrics

`UsageMetricAggregateResponse admin().usageMetrics().aggregate(UsageMetricAggregateParamsparams, RequestOptionsrequestOptions = RequestOptions.none())`

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

- `UsageMetricAggregateParams params`

  - `String dayOnOrAfter`

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

  - `String dayOnOrBefore`

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

  - `List<String> groupBy`

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

  - `Optional<List<EventType>> eventTypes`

    Filter by event types

    - `AUDIO_SECONDS_PARSED("audio_seconds_parsed")`

    - `CHART_PARSING_AGENTIC("chart_parsing_agentic")`

    - `CHART_PARSING_EFFICIENT("chart_parsing_efficient")`

    - `CHART_PARSING_PLUS("chart_parsing_plus")`

    - `CHAT_MESSAGE_SENT("chat_message_sent")`

    - `CONFIDENCE_SCORE_HIGH("confidence_score_high")`

    - `DIRECTORY_COUNT_SNAPSHOT("directory_count_snapshot")`

    - `DIRECTORY_FILE_COUNT_SNAPSHOT("directory_file_count_snapshot")`

    - `DIRECTORY_FILES_EXPORTED("directory_files_exported")`

    - `DIRECTORY_FILES_INGESTED("directory_files_ingested")`

    - `DIRECTORY_PAGES_EXPORTED("directory_pages_exported")`

    - `EXTRACTION_NUM_PAGES("extraction_num_pages")`

    - `FORM_PARSING_PAGES("form_parsing_pages")`

    - `IMAGE_CLASSIFIED("image_classified")`

    - `INDEX_RETRIEVE_QUERY("index_retrieve_query")`

    - `LAYOUT_AWARE_CHART_EXTRACTION("layout_aware_chart_extraction")`

    - `LAYOUT_AWARE_PARSING("layout_aware_parsing")`

    - `LAYOUT_EXTRACTED("layout_extracted")`

    - `PAGES_CLASSIFIED("pages_classified")`

    - `PAGES_EMBEDDED("pages_embedded")`

    - `PAGES_INDEXED("pages_indexed")`

    - `PAGES_PARSED("pages_parsed")`

    - `PAGES_SPLIT("pages_split")`

    - `PAGES_VERIFIED("pages_verified")`

    - `PRECISE_BBOX_EXTRACTION("precise_bbox_extraction")`

    - `SET_TOTAL_INDEXES("set_total_indexes")`

    - `SET_TOTAL_PAGES_INDEXED("set_total_pages_indexed")`

    - `SPREADSHEET_REGIONS_EXTRACTED("spreadsheet_regions_extracted")`

    - `STORED_FILE_COUNT("stored_file_count")`

    - `STORED_FILE_MB("stored_file_mb")`

  - `Optional<String> organizationId`

    Filter by organization ID

  - `Optional<String> projectId`

    Filter by project ID

  - `Optional<String> userId`

    Filter by user ID

### Returns

- `class UsageMetricAggregateResponse:`

  Response containing usage metrics aggregated by one or more dimensions.

  - `List<Bucket> buckets`

    The aggregation buckets, ordered by total credits descending

    - `Dimensions dimensions`

      The dimension values that define this bucket

    - `long metricCount`

      Number of metric rows in this bucket

    - `TotalCredits totalCredits`

      Total credits consumed by metrics in this bucket

      - `double`

      - `String`

    - `long totalValue`

      Total of the metric `value` field in this bucket

  - `List<GroupBy> groupBy`

    The dimensions the metrics were grouped by

    - `DAY("day")`

    - `EVENT_TYPE("event_type")`

    - `ORGANIZATION_ID("organization_id")`

    - `PROJECT_ID("project_id")`

    - `USER_ID("user_id")`

### Example

```java
package ai.llamaindex.llamacloudadmin.example;

import ai.llamaindex.llamacloudadmin.client.LlamaCloudAdminClient;
import ai.llamaindex.llamacloudadmin.client.okhttp.LlamaCloudAdminOkHttpClient;
import ai.llamaindex.llamacloudadmin.models.admin.usagemetrics.UsageMetricAggregateParams;
import ai.llamaindex.llamacloudadmin.models.admin.usagemetrics.UsageMetricAggregateResponse;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        LlamaCloudAdminClient client = LlamaCloudAdminOkHttpClient.fromEnv();

        UsageMetricAggregateParams params = UsageMetricAggregateParams.builder()
            .dayOnOrAfter("day_on_or_after")
            .dayOnOrBefore("day_on_or_before")
            .addGroupBy("string")
            .build();
        UsageMetricAggregateResponse response = client.admin().usageMetrics().aggregate(params);
    }
}
```

#### Response

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