## Aggregate Usage Metrics

`client.Admin.UsageMetrics.Aggregate(ctx, query) (*AdminUsageMetricAggregateResponse, error)`

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

  - `DayOnOrAfter param.Field[string]`

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

  - `DayOnOrBefore param.Field[string]`

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

  - `GroupBy param.Field[[]string]`

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

  - `EventTypes param.Field[[]string]`

    Filter by event types

    - `const AdminUsageMetricAggregateParamsEventTypeAudioSecondsParsed AdminUsageMetricAggregateParamsEventType = "audio_seconds_parsed"`

    - `const AdminUsageMetricAggregateParamsEventTypeChartParsingAgentic AdminUsageMetricAggregateParamsEventType = "chart_parsing_agentic"`

    - `const AdminUsageMetricAggregateParamsEventTypeChartParsingEfficient AdminUsageMetricAggregateParamsEventType = "chart_parsing_efficient"`

    - `const AdminUsageMetricAggregateParamsEventTypeChartParsingPlus AdminUsageMetricAggregateParamsEventType = "chart_parsing_plus"`

    - `const AdminUsageMetricAggregateParamsEventTypeChatMessageSent AdminUsageMetricAggregateParamsEventType = "chat_message_sent"`

    - `const AdminUsageMetricAggregateParamsEventTypeConfidenceScoreHigh AdminUsageMetricAggregateParamsEventType = "confidence_score_high"`

    - `const AdminUsageMetricAggregateParamsEventTypeDirectoryCountSnapshot AdminUsageMetricAggregateParamsEventType = "directory_count_snapshot"`

    - `const AdminUsageMetricAggregateParamsEventTypeDirectoryFileCountSnapshot AdminUsageMetricAggregateParamsEventType = "directory_file_count_snapshot"`

    - `const AdminUsageMetricAggregateParamsEventTypeDirectoryFilesExported AdminUsageMetricAggregateParamsEventType = "directory_files_exported"`

    - `const AdminUsageMetricAggregateParamsEventTypeDirectoryFilesIngested AdminUsageMetricAggregateParamsEventType = "directory_files_ingested"`

    - `const AdminUsageMetricAggregateParamsEventTypeDirectoryPagesExported AdminUsageMetricAggregateParamsEventType = "directory_pages_exported"`

    - `const AdminUsageMetricAggregateParamsEventTypeExtractionNumPages AdminUsageMetricAggregateParamsEventType = "extraction_num_pages"`

    - `const AdminUsageMetricAggregateParamsEventTypeFormParsingPages AdminUsageMetricAggregateParamsEventType = "form_parsing_pages"`

    - `const AdminUsageMetricAggregateParamsEventTypeImageClassified AdminUsageMetricAggregateParamsEventType = "image_classified"`

    - `const AdminUsageMetricAggregateParamsEventTypeIndexRetrieveQuery AdminUsageMetricAggregateParamsEventType = "index_retrieve_query"`

    - `const AdminUsageMetricAggregateParamsEventTypeLayoutAwareChartExtraction AdminUsageMetricAggregateParamsEventType = "layout_aware_chart_extraction"`

    - `const AdminUsageMetricAggregateParamsEventTypeLayoutAwareParsing AdminUsageMetricAggregateParamsEventType = "layout_aware_parsing"`

    - `const AdminUsageMetricAggregateParamsEventTypeLayoutExtracted AdminUsageMetricAggregateParamsEventType = "layout_extracted"`

    - `const AdminUsageMetricAggregateParamsEventTypePagesClassified AdminUsageMetricAggregateParamsEventType = "pages_classified"`

    - `const AdminUsageMetricAggregateParamsEventTypePagesEmbedded AdminUsageMetricAggregateParamsEventType = "pages_embedded"`

    - `const AdminUsageMetricAggregateParamsEventTypePagesIndexed AdminUsageMetricAggregateParamsEventType = "pages_indexed"`

    - `const AdminUsageMetricAggregateParamsEventTypePagesParsed AdminUsageMetricAggregateParamsEventType = "pages_parsed"`

    - `const AdminUsageMetricAggregateParamsEventTypePagesSplit AdminUsageMetricAggregateParamsEventType = "pages_split"`

    - `const AdminUsageMetricAggregateParamsEventTypePagesVerified AdminUsageMetricAggregateParamsEventType = "pages_verified"`

    - `const AdminUsageMetricAggregateParamsEventTypePreciseBboxExtraction AdminUsageMetricAggregateParamsEventType = "precise_bbox_extraction"`

    - `const AdminUsageMetricAggregateParamsEventTypeSetTotalIndexes AdminUsageMetricAggregateParamsEventType = "set_total_indexes"`

    - `const AdminUsageMetricAggregateParamsEventTypeSetTotalPagesIndexed AdminUsageMetricAggregateParamsEventType = "set_total_pages_indexed"`

    - `const AdminUsageMetricAggregateParamsEventTypeSpreadsheetRegionsExtracted AdminUsageMetricAggregateParamsEventType = "spreadsheet_regions_extracted"`

    - `const AdminUsageMetricAggregateParamsEventTypeStoredFileCount AdminUsageMetricAggregateParamsEventType = "stored_file_count"`

    - `const AdminUsageMetricAggregateParamsEventTypeStoredFileMB AdminUsageMetricAggregateParamsEventType = "stored_file_mb"`

  - `OrganizationID param.Field[string]`

    Filter by organization ID

  - `ProjectID param.Field[string]`

    Filter by project ID

  - `UserID param.Field[string]`

    Filter by user ID

### Returns

- `type AdminUsageMetricAggregateResponse struct{…}`

  Response containing usage metrics aggregated by one or more dimensions.

  - `Buckets []AdminUsageMetricAggregateResponseBucket`

    The aggregation buckets, ordered by total credits descending

    - `Dimensions map[string, string]`

      The dimension values that define this bucket

    - `MetricCount int64`

      Number of metric rows in this bucket

    - `TotalCredits AdminUsageMetricAggregateResponseBucketTotalCreditsUnion`

      Total credits consumed by metrics in this bucket

      - `float64`

      - `string`

    - `TotalValue int64`

      Total of the metric `value` field in this bucket

  - `GroupBy []string`

    The dimensions the metrics were grouped by

    - `const AdminUsageMetricAggregateResponseGroupByDay AdminUsageMetricAggregateResponseGroupBy = "day"`

    - `const AdminUsageMetricAggregateResponseGroupByEventType AdminUsageMetricAggregateResponseGroupBy = "event_type"`

    - `const AdminUsageMetricAggregateResponseGroupByOrganizationID AdminUsageMetricAggregateResponseGroupBy = "organization_id"`

    - `const AdminUsageMetricAggregateResponseGroupByProjectID AdminUsageMetricAggregateResponseGroupBy = "project_id"`

    - `const AdminUsageMetricAggregateResponseGroupByUserID AdminUsageMetricAggregateResponseGroupBy = "user_id"`

### Example

```go
package main

import (
  "context"
  "fmt"

  "github.com/run-llama/llamacloud-admin-go"
  "github.com/run-llama/llamacloud-admin-go/option"
)

func main() {
  client := llamacloudadmin.NewClient(
    option.WithAPIKey("My API Key"),
  )
  response, err := client.Admin.UsageMetrics.Aggregate(context.TODO(), llamacloudadmin.AdminUsageMetricAggregateParams{
    DayOnOrAfter: "day_on_or_after",
    DayOnOrBefore: "day_on_or_before",
    GroupBy: []string{"string"},
  })
  if err != nil {
    panic(err.Error())
  }
  fmt.Printf("%+v\n", response.Buckets)
}
```

#### Response

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