---
title: "Get usage summary"
method: GET
path: "/usage"
tags: ["Usage"]
---

# Get usage summary

`GET /usage`

## Request

- Base URL: `https://app.gc.ai/api/external/v1`
- URL: `https://app.gc.ai/api/external/v1/usage`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/gc-ai/apis/gc-ai-external-api/docs/usage/get.ts> (a function with typed inputs; its response is checked against the schema)

Organization-wide product-usage summary by channel: `web` (web app), `word` (Word add-in), and `api`.

Requires an org-scoped API key: usage is reported org-wide, so a user-scoped key receives a 403. For credit/billing totals, use `GET /v1/credit-usage`.

Note: web/word counts are sourced from product analytics; day boundaries for those channels are approximate (UTC).

## Query parameters

- `start_date` string, required: Inclusive range start (`YYYY-MM-DD`).
- `end_date` string, required: Inclusive range end (`YYYY-MM-DD`).
- `timezone` string: IANA timezone for the api channel day boundaries (default `UTC`).

## Response `200`

Usage summary for the requested range

- UsageSummaryResponse
  - `start_date` string, required: Inclusive range start.
  - `end_date` string, required: Inclusive range end.
  - `timezone` string, required: IANA timezone used for day boundaries.
  - `web` WebUsage, required: Web-app activity.
    - `messages` number, required: Web-app chat messages sent.
    - `web_pages_scraped` number, required: Web pages read by GC AI to compose answers.
    - `files_uploaded` number, required: Files uploaded.
  - `word` WordUsage, required: Word add-in activity.
    - `messages` number, required: Word add-in messages sent.
    - `redlines_applied` number, required: Redlines applied from the Word add-in.
    - `drafts_applied` number, required: Drafts applied from the Word add-in.
  - `api` ApiUsage, required: API activity.
    - `requests` number, required: Total billable API requests across all operations.
    - `by_operation` object, required: Billable API requests keyed by operation (e.g. `chat:completions`, `playbook:run`).

## Other responses

- `400`: Invalid date range or timezone (bad calendar date, end before start, unknown timezone, or range over 366 days)
- `401`: Missing or malformed API key
- `403`: Usage requires an org-scoped API key
- `429`: Rate limit exceeded. See [Rate Limits](https://docs.gc.ai/api-reference/concepts/rate-limits) for the tiers, limits, and how to back off.
- `500`: Internal server error
- `503`: Service temporarily unavailable

---

[API](https://skmtc.dev/gc-ai/apis/gc-ai-external-api.md) - [All operations](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gc-ai/apis/gc-ai-external-api/revisions/2bbdfddf7107?raw)