---
title: "Get credit balance time series"
method: GET
path: "/billing/credits/balance-timeseries"
tags: ["credits"]
---

# Get credit balance time series

`GET /billing/credits/balance-timeseries`

## Request

- Base URL: `https://api.schematichq.com`
- URL: `https://api.schematichq.com/billing/credits/balance-timeseries`
- Auth: API key in header `X-Schematic-Api-Key`

## Query parameters

- `billing_credit_id` string, required
- `company_id` string, required
- `end_time` string, date-time, required
- `start_time` string, date-time, required

## Response `200`

OK

- object
  - `data` CreditBalanceTimeSeriesResponseData, required
    - `balance_points` CreditBalancePointResponseData[], required
      - `balance` number, double, required
      - `consumed` number, double, required: Credits drawn during this day, as a positive number
      - `consumed_by_feature` CreditBalanceFeatureConsumptionResponseData[], required
        - `amount` number, double, required
        - `feature_id` string, required
        - `feature_name` string, required
      - `timestamp` string, date-time, required: Start of the UTC day this point covers
    - `billing_credit_id` string, required
    - `events` CreditBalanceEventResponseData[], required
      - `amount` number, double, required
      - `event_type` 'adjustment' | 'charge' | 'grant' | 'settlement' | 'transfer' | 'usage' | 'zero_out', required
      - `grant_id` string, nullable
      - `grant_reason` 'adjustment' | 'billing_credit_auto_topup' | 'free' | 'plan' | 'postpaid_forgiven' | 'postpaid_overdraft' | 'postpaid_settlement' | 'purchased' | 'rollover'
      - `plan_id` string, nullable
      - `timestamp` string, date-time, required
      - `zeroed_out_reason` 'customer_archived' | 'expired' | 'integration_uninstalled' | 'license_retired' | 'manual' | 'plan_change' | 'plan_period_reset' | 'reconciled'
    - `external` boolean, required: True when an external provider owns this credit's ledger, in which case Schematic has no history to report and the series is empty
  - `params` object, required: Input parameters
    - `billing_credit_id` string
    - `company_id` string
    - `end_time` string, date-time
    - `start_time` string, date-time

## Other responses

- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not found
- `500`: Server error

## Changes

> 230 revisions in range; 1 not diffed.

- **2026-10-09** `370eaa4db0ab`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/schematichq/apis/schematic-api/changes/billing/credits/balance-timeseries/get.md)

---

[API](https://skmtc.dev/schematichq/apis/schematic-api.md) - [All operations](https://skmtc.dev/schematichq/apis/schematic-api/llms.txt) - [OpenAPI document](https://skmtc.dev/schematichq/apis/schematic-api/revisions/64cb7e17c236?raw)