---
title: "GET /orgs/{org_id}/billing/overage"
method: GET
path: "/orgs/{org_id}/billing/overage"
tags: ["billing"]
---

# GET /orgs/{org_id}/billing/overage

`GET /orgs/{org_id}/billing/overage`

Get overage credit usage for the current billing period.

## Path parameters

- `org_id` string, required

## Response `200`

Overage usage summary

- OverageSummary — Customer-facing overage usage summary for the current credits period. `used_credits = invoiced_credits + pending_credits`. `invoiced_credits` is the real metered overage billed on finalized invoices this period (see [`overage_summary`]); `pending_credits` is the headline "extra usage you'll be billed for" number, and a non-zero `invoiced_credits` means an interim (threshold-driven) invoice has already billed part of this period.
  - `cap_credits` integer, nullable — Org-configured ceiling on overage credits for the period. `null` means unlimited (or no cap configured); only meaningful when `enabled`.
  - `enabled` boolean, required — Whether usage-based overage billing is currently enabled for the org.
  - `invoiced_credits` integer, required — Overage credits already included on a finalized invoice this period.
  - `pending_credits` integer, required — Overage credits accrued this period that have not been invoiced yet.
  - `period_end` string, date-time, nullable — End of the current credits period — when pending overage bills if no interim invoice fires first. `null` when there is no metered window.
  - `period_start` string, date-time, nullable — Start of the current credits period. `null` when the org has no metered billing window (e.g. free plan with no period anchor).
  - `rate_cents_per_1k` integer, nullable — Metered overage rate in cents per 1,000 credits. `null` when overage pricing is unavailable for the plan.
  - `threshold_usd` integer, nullable — Outstanding overage value (whole USD) that triggers an interim invoice. `null` means overage bills only at the end of the period.
  - `used_credits` integer, required — Total overage credits consumed this period (`invoiced` + `pending`).

## Other responses

- `403` — Forbidden
- `500` — Internal server error

## Changes

- **2026-07-03** `e1c81d0f4235` — 1 info
  - endpoint added
- **2026-03-16** `eb2c08128881` — 1 breaking
  - api path removed without deprecation

[Change history](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/changes/orgs/:org_id/billing/overage/get.md)

---

[API](https://skmtc.dev/timbal-ai/apis/timbal-platform-api.md) · [All operations](https://skmtc.dev/timbal-ai/apis/timbal-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/timbal-ai/timbal-platform-api/revisions/dd7e398ce0d3/schema)