---
title: "Export complete metered usage over a half-open UTC window."
method: GET
path: "/v1/finops/usage"
tags: ["FinOps"]
---

# Export complete metered usage over a half-open UTC window.

`GET /v1/finops/usage`

## Request

- Base URL: `https://api.provider.example`
- URL: `https://api.provider.example/v1/finops/usage`
- Auth: one of:
  - HTTP bearer
  - OAuth 2
    - Authorization code: `https://provider.example/oauth/authorize`
    - Token URL: `https://provider.example/oauth/token` scopes: `billing.usage.read`

## Query parameters

- `start` string, date-time, required
- `end` string, date-time, required
- `granularity` '1h' | '1d', required
- `limit` integer
- `cursor` string

## Response `200`

One page of usage meter records.

- UsagePage
  - `data` UsageRecord[], required
    - `x_RecordId` string, required
    - `x_RecordUpdatedAt` string, date-time, required
    - `x_Granularity` '1h' | '1d', required
    - `ChargePeriodStart` string, date-time, required
    - `ChargePeriodEnd` string, date-time, required
    - `ServiceProviderName` string, required
    - `ServiceCategory` 'AI and Machine Learning', required
    - `ServiceSubcategory` string, nullable
    - `ServiceName` string, required
    - `SkuId` string, nullable, required
    - `SkuMeter` string, nullable, required
    - `x_ModelId` string, nullable
    - `x_ProjectId` string, nullable
    - `x_WorkspaceId` string, nullable
    - `x_ApiKeyId` string, nullable
    - `x_ServiceTier` string, nullable
    - `x_WorkloadType` string, nullable
    - `x_UpstreamProvider` string, nullable
    - `ConsumedQuantity` string, required
    - `ConsumedUnit` string, required
    - `x_UsageType` union, required
      - 'input_tokens' | 'output_tokens' | 'cache_read_tokens' | 'cache_write_5m_tokens' | 'cache_write_1h_tokens' | 'input_audio_tokens' | 'output_audio_tokens' | 'requests' | 'audio_seconds' | 'characters' | 'events' | 'session_minutes' | 'credits'
      - string
  - `next_cursor` string, nullable, required
  - `as_of` string, date-time, required
  - `available_through` string, date-time, required

## Other responses

- `400`: Invalid query or unsupported capability.
- `401`: Missing or invalid credential.
- `403`: Valid credential without the required scope or account access.
- `429`: Provider rate limit exceeded.

---

[API](https://skmtc.dev/superpenguin/apis/superpenguin-focus-ai-provider-profile.md) - [All operations](https://skmtc.dev/superpenguin/apis/superpenguin-focus-ai-provider-profile/llms.txt) - [OpenAPI document](https://skmtc.dev/superpenguin/apis/superpenguin-focus-ai-provider-profile/revisions/37d822e68d01?raw)