---
title: "Get usage overview for the current billing period."
method: GET
path: "/usage/v2/usage-overview/"
tags: ["usage"]
---

# Get usage overview for the current billing period.

`GET /usage/v2/usage-overview/`

## Request

- Base URL: `http://localhost:8000`
- URL: `http://localhost:8000/usage/v2/usage-overview/`
- Auth: one of:
  - API key in header `X-Api-Key`
  - API key in header `X-Secret-Key`

Returns per-dimension totals, free allowances, estimated costs,
and projected month-end usage.

Query params:
    period: YYYY-MM (default: current month)
    workspace_id: optional (filter by workspace)

## Query parameters

- `period` string
- `period_end` string
- `workspace_id` string, uuid

## Response `200`

OK

- UsageOverviewResponse
  - `status` boolean, required
  - `result` UsageOverviewResult, required
    - `plan` string, required
    - `plan_display_name` string, required
    - `platform_fee` number, required
    - `period` string, required
    - `billing_period_start` string, required
    - `billing_period_end` string, required
    - `total_estimated_cost` number, required
    - `total_with_platform` number, required
    - `dimensions` UsageOverviewDimension[], required
      - `key` string, required
      - `display_name` string, required
      - `display_unit` string, required
      - `current_usage` number, required
      - `current_usage_raw` number, required
      - `free_allowance` number, required
      - `projected_usage` number, required
      - `estimated_cost` number, required
      - `tier_breakdown` UsageTierBreakdown[]
        - `tier_start` number
        - `tier_end` number, nullable
        - `quantity` number
        - `rate` number
        - `cost` number
      - `usage_pct` number, required
    - `pending_cancel` boolean, required
    - `cancel_at` string, nullable

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `402`: Payment Required
- `403`: Forbidden
- `404`: Not Found
- `500`: Internal Server Error
- `default`: Default error response

---

[API](https://skmtc.dev/futureagi/apis/future-agi-management-api.md) · [All operations](https://skmtc.dev/futureagi/apis/future-agi-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/futureagi/apis/future-agi-management-api/revisions/c8684118e142?raw)