---
title: "Account Usage"
method: GET
path: "/account/usage"
tags: ["Account"]
---

# Account Usage

`GET /account/usage`

## Request

- Base URL: `https://api.falpha.ai`
- URL: `https://api.falpha.ai/account/usage`
- Auth: one of:
  - API key in query parameter `api_key`
  - API key in header `X-API-Key`

Aggregated API usage for the calling key over the last N days (default 30): totals by day, by endpoint, and by client surface (excel / sdk-python / api). Surfaces are attributed via the optional X-Falpha-Surface request header. Available to any valid API key. Counts successful and failed requests (failures are recorded by the metering middleware with their status_code).

## Query parameters

- `days` integer: Aggregation window in days (max 90)

## Response `200`

Successful Response

- UsageResponse
  - `window_days` integer, required: Size of the aggregation window in days
  - `since` string, date-time, required: UTC start of the aggregation window
  - `total` integer, required: Total successful requests recorded in the window
  - `by_day` UsageBucket[], required
    - `key` string, required: Bucket label: a YYYY-MM-DD day, an endpoint path, or a surface name
    - `count` integer, required
  - `by_endpoint` UsageBucket[], required
    - `key` string, required: Bucket label: a YYYY-MM-DD day, an endpoint path, or a surface name
    - `count` integer, required
  - `by_surface` UsageBucket[], required: Split by client surface: excel, sheets, sdk-python, zapier, or api (default)
    - `key` string, required: Bucket label: a YYYY-MM-DD day, an endpoint path, or a surface name
    - `count` integer, required
  - `by_client` UsageBucket[]: Split by anonymous install id (X-Falpha-Client header); requests without one bucket under '-'
    - `key` string, required: Bucket label: a YYYY-MM-DD day, an endpoint path, or a surface name
    - `count` integer, required
  - `meter` object: Unified work meter summed over the window: db_calls, db_docs, db_ms (see dbmeter contract). Requests are traffic; the meter is work.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/falpha/apis/falpha-ai-api.md) · [All operations](https://skmtc.dev/falpha/apis/falpha-ai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/falpha/apis/falpha-ai-api/revisions/d437fee1fac5?raw)