Query Usage with Go

Use client.Query for analytics and usage-event inspection.

Aggregate Usage

usage, err := client.Query.UsageForProject(ctx, "proj_gateway", types.UsageAnalyticsQueryRequest{
  Metrics:    []string{"input_tokens"},
  StartTime:  1781222400,
  EndTime:    1781308800,
  GroupBy:    []string{"model"},
  Measures:   []string{"quantity", "amount"},
  Filters:    map[string]string{"provider": "openai"},
  BucketSize: "1h",
})
if err != nil {
  return err
}

for _, row := range usage.Rows {
  fmt.Println(row.Dimensions, row.Measures)
}

Use UsageForProject for project-scoped analytics and Report for a saved report query.

For metric-based analytics, send Metrics explicitly even for a single metric. The singular Metric field remains only as a compatibility alias.

Bill Query

BillForProject calls /usage/bills/query and decodes the bill response, including request_count, per-metric amounts, and cursor pagination.

bill, err := client.Query.BillForProject(ctx, "proj_gateway", types.UsageBillQueryRequest{
  BillingAccountID: "acct_org_001",
  BucketSize:       "day",
  Timezone:         "Asia/Shanghai",
  StartTime:        1785081600,
  EndTime:          1785686400,
  Metrics:          []string{"input_tokens", "output_tokens"},
  GroupBy:          []string{"model"},
  Limit:            100,
})
if err != nil {
  return err
}

if bill.HasMore {
  fmt.Println("next cursor", bill.NextCursor)
}

Chart Series

Query.Chart converts bucketed analytics rows into sorted metric series for chart components.

series, err := client.Query.Chart(ctx, sdk.ChartQuery{
  ProjectID:  "proj_gateway",
  Metrics:    []string{"input_tokens", "output_tokens"},
  Measure:    "quantity",
  BucketSize: "5m",
  StartTime:  1781222400,
  EndTime:    1781308800,
})

Usage Events and Details

List project usage events:

events, err := client.Query.ListProjectUsageEvents(ctx, "proj_gateway", types.ListUsageEventLogsRequest{
  SubjectType: "user",
  SubjectID:   "user_123",
  StartTime:   1781222400,
  EndTime:     1781308800,
  Limit:       50,
})

List usage event details, including charge items:

details, err := client.Query.ListProjectUsageEventDetails(ctx, "proj_gateway", types.ListUsageEventLogsRequest{
  RawEventID: "raw_01hxy7f9q8m2",
  Limit:      10,
})

Supported Operations

Area	Methods
Analytics	UsageForProject, BillForProject, Report, Chart
Usage logs	ListUsageLogs, ListProjectUsageEvents, ListProjectUsageEventDetails