> ## Documentation Index
> Fetch the complete documentation index at: https://docs.signa.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Credits

> Pooled credit balance, grant breakdown, and expiry schedule

<Note>
  **Beta.** Credits are the single billing currency across the Signa API. This endpoint's schema is new and may evolve before general availability.
</Note>

## Overview

Returns the authenticated organization's pooled **credit** balance: the spendable
balance across all active grants, a breakdown of remaining credits by grant type
(`plan` vs `addon` vs `promo`), and the per-grant expiry schedule in consumption
order (plan first, then oldest-expiry-first).

Requires the `billing:read` scope. Querying credits does not consume any credits.

## Response

<ResponseField name="object" type="string">Always `"credit_balance"`.</ResponseField>
<ResponseField name="balance" type="integer">Authoritative spendable pooled balance. Reconciles exactly: `balance = (plan + addon + promo) - reserved - pending`. May be negative under the debt floor.</ResponseField>

<ResponseField name="grants" type="object">
  <Expandable title="Remaining credits by grant type">
    <ResponseField name="plan" type="integer">Remaining credits from plan grants.</ResponseField>
    <ResponseField name="addon" type="integer">Remaining credits from addon grants.</ResponseField>
    <ResponseField name="promo" type="integer">Remaining credits from promotional grants.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="reserved" type="integer">Credits held by open reservations (reserved but not yet settled or refunded).</ResponseField>
<ResponseField name="pending" type="integer">Billable spend not yet attributed to specific grants by the hourly applier.</ResponseField>

<ResponseField name="expiry_schedule" type="object[]">
  <Expandable title="Active grant">
    <ResponseField name="grant_id" type="string">Grant ID (`grant_...`).</ResponseField>
    <ResponseField name="type" type="string">One of `plan`, `addon`, `promo`.</ResponseField>
    <ResponseField name="amount" type="integer">Credits originally granted.</ResponseField>
    <ResponseField name="remaining" type="integer">Credits remaining on this grant (may be negative under debt).</ResponseField>
    <ResponseField name="effective_at" type="string">ISO timestamp for when the grant became usable.</ResponseField>
    <ResponseField name="expires_at" type="string">ISO timestamp for when the grant expires (exclusive).</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="request_id" type="string">Request ID for debugging.</ResponseField>

<ResponseExample>
  ```json theme={null}
  {
    "object": "credit_balance",
    "balance": 8500,
    "grants": {
      "plan": 8000,
      "addon": 500,
      "promo": 0
    },
    "reserved": 0,
    "pending": 0,
    "expiry_schedule": [
      {
        "grant_id": "grant_01HXYZPLAN",
        "type": "plan",
        "amount": 10000,
        "remaining": 8000,
        "effective_at": "2026-04-01T00:00:00.000Z",
        "expires_at": "2026-05-01T00:00:00.000Z"
      },
      {
        "grant_id": "grant_01HXYZADDON",
        "type": "addon",
        "amount": 500,
        "remaining": 500,
        "effective_at": "2026-04-10T00:00:00.000Z",
        "expires_at": "2027-04-10T00:00:00.000Z"
      }
    ],
    "request_id": "req_abc123"
  }
  ```
</ResponseExample>

## Code Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api.signa.so/v1/organization/credits" \
    -H "Authorization: Bearer sig_xxxxxxxxxxxx"
  ```

  ```typescript TypeScript theme={null}
  import { Signa } from "@signa-so/sdk";

  const signa = new Signa({ api_key: "sig_xxxxxxxxxxxx" });

  const credits = await signa.organization.credits();
  console.log(credits.balance, credits.grants.plan, credits.grants.addon);
  ```

  ```python Python theme={null}
  import requests

  resp = requests.get(
      "https://api.signa.so/v1/organization/credits",
      headers={"Authorization": "Bearer sig_xxxxxxxxxxxx"},
  )
  credits = resp.json()
  ```
</CodeGroup>

## Errors

| Status | Type           | Description                  |
| ------ | -------------- | ---------------------------- |
| 401    | `unauthorized` | Missing or invalid API key   |
| 403    | `forbidden`    | API key lacks `billing:read` |
| 429    | `rate_limited` | Too many requests            |

## Related Endpoints

* [Get Usage Summary](/api-reference/administration/get-usage-summary) -- daily usage breakdown in credit terms
* [Get Usage](/api-reference/administration/get-usage) -- current billing period totals by endpoint type