---
title: "Get Monthly Usage Endpoint"
method: GET
path: "/billing/usages/monthly"
tags: ["/billing"]
---

# Get Monthly Usage Endpoint

`GET /billing/usages/monthly`

## Request

- Base URL: `https://api.contextual.ai/v1`
- URL: `https://api.contextual.ai/v1/billing/usages/monthly`
- Auth: HTTP bearer

Get monthly usage data for a tenant with validation for year and month parameters.

Args: request: Request object containing year and month with validation user_context: User context with tenant admin permissions resource_id: Optional[UUID]. If provided, get usage data for a specific resource. Otherwise, get aggregated usage data across all resources.

Returns: Monthly usage records for the specified month and year

## Query parameters

- `year` integer, required
- `month` integer, required
- `resource_id` string, uuid, nullable

## Response `200`

Successful Response

- MonthlyUsageResponse: Response to GET /billing/usage/monthly request
  - `usages` DailyUsage[], required: List of daily usages
    - `date` string, date, required: Date of the usage
    - `usage_type` 'QUERY_REFORMULATION_INPUT_TOKEN' | 'QUERY_REFORMULATION_OUTPUT_TOKEN' | 'QUERY_EXPANSION_INPUT_TOKEN' | 'QUERY_EXPANSION_OUTPUT_TOKEN' | 'QUERY_FILTER_TOKEN' | 'QUERY_RETRIEVAL_TOKEN' | 'QUERY_RERANK_TOKEN' | 'QUERY_GENERATION_INPUT_TOKEN' | 'QUERY_GENERATION_OUTPUT_TOKEN' | 'QUERY_CONTEXTUALIZATION_TOKEN' | 'QUERY_GROUNDEDNESS_TOKEN' | 'QUERY_PLANNING_INPUT_TOKEN' | 'QUERY_PLANNING_OUTPUT_TOKEN' | 'QUERY_TRANSLATION_INPUT_TOKEN' | 'QUERY_TRANSLATION_OUTPUT_TOKEN' | 'QUERY_REQUEST' | 'TUNE_REQUEST' | 'EVAL_REQUEST' | 'INGEST_BASIC_PAGE' | 'INGEST_STANDARD_PAGE' | 'INGEST_V3_STANDARD_PAGE' | 'INGEST_V3_ADVANCED_PAGE' | 'INGEST_V3_PREMIUM_PAGE' | 'PARSE_BASIC_PAGE' | 'PARSE_STANDARD_PAGE' | 'RERANK_TOKEN' | 'RERANK_V2_MINI_TOKEN' | 'RERANK_V2_TOKEN' | 'GENERATE_INPUT_TOKEN' | 'GENERATE_OUTPUT_TOKEN' | 'LMUNIT_TOKEN' | 'ACL_COST' | 'STRUCTURED_EXTRACTION_COST' | 'STRUCTURED_EXTRACTION_INPUT_TOKENS' | 'STRUCTURED_EXTRACTION_OUTPUT_TOKENS' | 'STRUCTURED_EXTRACTION_CACHED_TOKENS' | 'STRUCTURED_EXTRACTION_REASONING_TOKENS', required
    - `quantity` integer, required: Usage quantity
    - `price` number, required: Price per unit

## Other responses

- `422`: Validation Error

## Changes

- **2026-10-16** `4abdda722de9`: 1 info
  - endpoint added
- **2026-01-13** `ca7f807eec8b`: 1 breaking
  - api path removed without deprecation
- **2025-10-28** `c8152db45500`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/contextualai/apis/endpoints/changes/billing/usages/monthly/get.md)

---

[API](https://skmtc.dev/contextualai/apis/endpoints.md) - [All operations](https://skmtc.dev/contextualai/apis/endpoints/llms.txt) - [OpenAPI document](https://skmtc.dev/contextualai/apis/endpoints/revisions/4abdda722de9?raw)