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

# Get credit usage

`GET /credit-usage`

## Request

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

Billing view of the organization's credit consumption, broken down by billable operation and by day, with rate-card pricing.

Requires an org-scoped API key: credit usage is an organization-level concern. User-scoped keys receive a 403.

If rate-card pricing can't be resolved for every observed operation, `pricing_available` is `false` and all credit fields are null; raw request counts are still returned.

## 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 day boundaries (default `UTC`), e.g. `America/New_York`.

## Response `200`

Credit usage for the requested range

- CreditUsageResponse
  - `start_date` string, required: Inclusive range start.
  - `end_date` string, required: Inclusive range end.
  - `timezone` string, required: IANA timezone used for day boundaries.
  - `pricing_available` boolean, required: Whether rate-card pricing could be resolved for every observed operation. When false, all credit fields are null and only raw request counts are returned.
  - `total_credits` number, nullable, required: Total credits across all operations over the range. Null when pricing is unavailable.
  - `lines` CreditUsageLine[], required: Per-operation usage and credit totals over the range.
    - `api` string, required: The billable operation, e.g. `chat:completions` or `playbook:run`.
    - `requests` number, required: Total billable units consumed for this line over the range.
    - `unit` string, nullable, required: Display label for one billable unit (e.g. `request`). Null when pricing is unavailable.
    - `credits_per_unit` number, nullable, required: Credits charged per unit, from the current rate card. Null when pricing is unavailable.
    - `credits` number, nullable, required: Total credits for this line (`requests × credits_per_unit`). Null when pricing is unavailable.
  - `daily` CreditUsageDay[], required: Daily usage buckets across the full range (days with no usage have an empty `usage` object).
    - `date` string, required: Calendar day (`YYYY-MM-DD`) in the requested timezone.
    - `usage` object, required: Billable units consumed that day, keyed by billable operation. Operations with no usage are omitted.

## 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`: Credit 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)