Aggregate Usage Metrics

UsageMetricAggregateResponse admin().usageMetrics().aggregate(, )

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

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

ReturnsExpand Collapse

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

One of the following:

double

String

long totalValue

Total of the metric value field in this bucket

List<GroupBy> groupBy

The dimensions the metrics were grouped by

One of the following:

DAY("day")

EVENT_TYPE("event_type")

ORGANIZATION_ID("organization_id")

PROJECT_ID("project_id")

USER_ID("user_id")

Aggregate Usage Metrics

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);
    }
}

{
  "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"
  ]
}