Get spend history and contract usage from the Depot API

19 NOV, 2026

The spend and contract credit numbers in Billing & usage settings are now available through the Depot API. Pull them into your own dashboards, FinOps tools, or alerts with three BillingService methods:

  • GetSpendHistory returns paid invoice totals for up to the past 24 months, plus an estimate for the current period. Each invoice has a total and an on_demand amount, which is what was billed beyond your credit instead of drawn from a contract's usage bucket. During an annual contract, it also lists finalized invoices that are not yet paid, and covers the full contract term when it started more than 24 months ago.
  • GetContractUsage returns your annual contract dates, usage bucket value, starting credit, every change to that credit since the contract started, and the credit remaining. Current period usage comes out of the remaining credit once its invoice is finalized.
  • ListInvoiceLineItems now accepts upcoming as the invoice ID to list the current period's line items so far.

Amounts are in US cents. These methods are read-only and require an organization API token or an organization owner's user token. With a user token, set the X-Depot-Org header to your organization ID. They're available to organizations billed through Stripe in US dollars.

curl https://api.depot.dev/depot.core.v1.BillingService/GetSpendHistory \
  -H "Authorization: Bearer $DEPOT_TOKEN" \
  -H 'Content-Type: application/json' \
  -H 'Connect-Protocol-Version: 1' \
  -d '{}'

Start building with Depot
in minutes