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

# List Balances

> Lists individual balances (one row per grant) across customers, live or expired: plan balances, standalone balances, top-ups, and pooled balances. Pages may hold fewer than `limit` rows while `has_more` is true.

export const DynamicResponseExample = ({json, statusCode = "200"}) => {
  const toCamelCase = str => {
    return str.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
  };
  const convertKeysToCamelCase = obj => {
    if (Array.isArray(obj)) {
      return obj.map(item => convertKeysToCamelCase(item));
    }
    if (obj !== null && typeof obj === "object") {
      return Object.keys(obj).reduce((acc, key) => {
        const camelKey = toCamelCase(key);
        acc[camelKey] = convertKeysToCamelCase(obj[key]);
        return acc;
      }, {});
    }
    return obj;
  };
  const [isTypeScript, setIsTypeScript] = useState(() => {
    if (typeof window !== "undefined") {
      try {
        const lang = localStorage.getItem("code");
        return JSON.parse(lang) === "typescript";
      } catch {
        return true;
      }
    }
    return true;
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      if (event.detail?.key === "code") {
        try {
          const value = JSON.parse(event.detail.value);
          setIsTypeScript(value === "typescript");
        } catch {}
      }
    };
    const pollInterval = setInterval(() => {
      try {
        const lang = localStorage.getItem("code");
        const value = JSON.parse(lang);
        setIsTypeScript(value === "typescript");
      } catch {}
    }, 300);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, []);
  const camelCaseJson = useMemo(() => convertKeysToCamelCase(json), [json]);
  const snakeCaseString = JSON.stringify(json, null, 2);
  const camelCaseString = JSON.stringify(camelCaseJson, null, 2);
  return <ResponseExample>
			{isTypeScript ? <CodeBlock language="json" filename={statusCode}>
					{camelCaseString}
				</CodeBlock> : <CodeBlock language="json" filename={statusCode}>
					{snakeCaseString}
				</CodeBlock>}
		</ResponseExample>;
};

export const DynamicResponseField = ({children, name, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedName = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(name) : name;
    } catch {
      return name;
    }
  }, [name, lang]);
  return <ResponseField name={resolvedName} {...props}>
			{children}
		</ResponseField>;
};

export const DynamicParamField = ({children, body, path, ...props}) => {
  const convertToCamelCase = str => {
    if (typeof str !== "string") return str;
    return str.replace(/[_-](\w)/g, (_, c) => c.toUpperCase());
  };
  const [lang, setLang] = useState(() => {
    if (typeof window !== "undefined") {
      const stored = localStorage.getItem("code");
      return stored || '"typescript"';
    }
    return '"typescript"';
  });
  useEffect(() => {
    const onMintlifyStorage = event => {
      const key = event.detail?.key;
      if (key === "code") {
        setLang(event.detail.value);
      }
    };
    const pollInterval = setInterval(() => {
      const current = localStorage.getItem("code");
      if (current && current !== lang) {
        setLang(current);
      }
    }, 500);
    document.addEventListener("mintlify-localstorage", onMintlifyStorage);
    return () => {
      document.removeEventListener("mintlify-localstorage", onMintlifyStorage);
      clearInterval(pollInterval);
    };
  }, [lang]);
  const resolvedBody = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(body) : body;
    } catch {
      return body;
    }
  }, [body, lang]);
  const resolvedPath = useMemo(() => {
    try {
      const value = JSON.parse(lang);
      const useCamelCase = value === "typescript";
      return useCamelCase ? convertToCamelCase(path) : path;
    } catch {
      return path;
    }
  }, [path, lang]);
  return <ParamField body={resolvedBody} path={resolvedPath} {...props}>
			{children}
		</ParamField>;
};

Lists individual balances, one row per grant: plan balances, standalone balances from `balances.create`, top-ups, and pooled balances. By default only active balances are returned; pass `statuses: ["expired"]` for balances whose plan expired or whose `expires_at` has passed.

Pass `plan_id: null` to list only balances that don't come from a plan. Rollovers are returned on the balance they belong to.

<Note>
  A page can hold fewer than `limit` rows (even zero) while `has_more` is `true`. Keep paginating until `has_more` is `false`.
</Note>

### Body Parameters

<DynamicParamField body="customer_id" type="string">
  Only return rows for this customer. Omit to list across every customer.
</DynamicParamField>

<DynamicParamField body="entity_id" type="string">
  Only return rows for this entity. Requires customer\_id.
</DynamicParamField>

<DynamicParamField body="limit" type="integer">
  Number of items to return. Default 50, hard ceiling 200.
</DynamicParamField>

<DynamicParamField body="start_cursor" type="string">
  Opaque pagination cursor. Empty string (default) requests the first page; use next\_cursor from a prior response for subsequent pages.
</DynamicParamField>

<DynamicParamField body="statuses" type="('active' | 'expired')[]">
  Statuses to include. Defaults to active. A balance is expired when its plan expired, or when a standalone balance passed its expires\_at.
</DynamicParamField>

<DynamicParamField body="plan_id" type="string | null">
  Only return balances from this plan. Pass null for standalone balances only (top-ups, balances.create, rollovers).
</DynamicParamField>

<DynamicParamField body="feature_id" type="string">
  Only return balances for this feature.
</DynamicParamField>

### Response

<DynamicResponseField name="list" type="object[]">
  Rows on this page.

  <Expandable title="properties">
    <DynamicResponseField name="id" type="string">
      The unique identifier for this balance breakdown.
    </DynamicResponseField>

    <DynamicResponseField name="plan_id" type="string | null">
      The plan ID this balance originates from, or null for standalone balances.
    </DynamicResponseField>

    <DynamicResponseField name="included_grant" type="number">
      Amount granted from the plan's included usage.
    </DynamicResponseField>

    <DynamicResponseField name="prepaid_grant" type="number">
      Amount granted from prepaid purchases or top-ups.
    </DynamicResponseField>

    <DynamicResponseField name="remaining" type="number">
      Remaining balance available for use.
    </DynamicResponseField>

    <DynamicResponseField name="usage" type="number">
      Amount consumed in the current period.
    </DynamicResponseField>

    <DynamicResponseField name="unlimited" type="boolean">
      Whether this balance has unlimited usage.
    </DynamicResponseField>

    <DynamicResponseField name="reset" type="object | null">
      Reset configuration for this balance, or null if no reset.

      <Expandable title="properties">
        <DynamicResponseField name="interval" type="'one_off' | 'minute' | 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'semi_annual' | 'year'">
          The reset interval (hour, day, week, month, etc.) or 'multiple' if combined from different intervals.
        </DynamicResponseField>

        <DynamicResponseField name="interval_count" type="number">
          Number of intervals between resets (eg. 2 for bi-monthly).
        </DynamicResponseField>

        <DynamicResponseField name="resets_at" type="number | null">
          Timestamp when the balance will next reset.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="price" type="object | null">
      Pricing configuration if this balance has usage-based pricing.

      <Expandable title="properties">
        <DynamicResponseField name="amount" type="number">
          The per-unit price amount.
        </DynamicResponseField>

        <DynamicResponseField name="tiers" type="object[]">
          Tiered pricing configuration if applicable.

          <Expandable title="properties">
            <DynamicResponseField name="to" type="number" />

            <DynamicResponseField name="amount" type="number" />

            <DynamicResponseField name="flat_amount" type="number" />
          </Expandable>
        </DynamicResponseField>

        <DynamicResponseField name="tier_behavior" type="'graduated' | 'volume'">
          How tiers are applied: graduated (split across bands) or volume (flat rate for the matched tier).
        </DynamicResponseField>

        <DynamicResponseField name="billing_units" type="number">
          The number of units per billing increment (eg. \$9 / 250 units).
        </DynamicResponseField>

        <DynamicResponseField name="billing_method" type="'prepaid' | 'usage_based'">
          Whether usage is prepaid or billed pay-per-use.
        </DynamicResponseField>

        <DynamicResponseField name="max_purchase" type="number | null">
          Maximum quantity that can be purchased, or null for unlimited.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="expires_at" type="number | null">
      Timestamp when this balance expires, or null for no expiration.
    </DynamicResponseField>

    <DynamicResponseField name="feature_id" type="string">
      The feature this balance is for.
    </DynamicResponseField>

    <DynamicResponseField name="status" type="'active' | 'expired'">
      Whether this balance is active or expired.
    </DynamicResponseField>

    <DynamicResponseField name="rollovers" type="object[]">
      Rollover balances carried over onto this balance.

      <Expandable title="properties">
        <DynamicResponseField name="granted" type="number">
          Amount originally rolled over from a previous period, before any of it was consumed.
        </DynamicResponseField>

        <DynamicResponseField name="balance" type="number">
          Amount of balance rolled over from a previous period.
        </DynamicResponseField>

        <DynamicResponseField name="expires_at" type="number">
          Timestamp when the rollover balance expires.
        </DynamicResponseField>
      </Expandable>
    </DynamicResponseField>

    <DynamicResponseField name="customer_id" type="string">
      The customer this balance belongs to.
    </DynamicResponseField>

    <DynamicResponseField name="entity_id" type="string | null">
      The entity this balance is scoped to, or null.
    </DynamicResponseField>

    <DynamicResponseField name="created_at" type="number">
      Timestamp when this balance was created.
    </DynamicResponseField>
  </Expandable>
</DynamicResponseField>

<DynamicResponseField name="has_more" type="boolean">
  Whether more results exist. A page may hold fewer than `limit` items (even zero) while `has_more` is true, so paginate until `has_more` is false.
</DynamicResponseField>

<DynamicResponseField name="next_cursor" type="string | null">
  Pass as start\_cursor to fetch the next page. Null when has\_more is false.
</DynamicResponseField>

<ResponseExample>
  ```json 200 theme={null}
  {
    "list": [
      {
        "id": "bonus_credits",
        "plan_id": null,
        "included_grant": 50,
        "prepaid_grant": 0,
        "remaining": 0,
        "usage": 50,
        "unlimited": false,
        "reset": {
          "interval": "one_off",
          "resets_at": null
        },
        "price": null,
        "expires_at": 1771999921437,
        "feature_id": "messages",
        "status": "expired",
        "rollovers": [],
        "customer_id": "cus_123",
        "entity_id": null,
        "created_at": 1769904000000
      }
    ],
    "has_more": false,
    "next_cursor": null
  }
  ```
</ResponseExample>


## OpenAPI

````yaml openapi POST /v1/balances.list
openapi: 3.1.0
info:
  title: Autumn API
  version: 2.4.0
servers:
  - url: https://api.useautumn.com
    description: Production server
security:
  - secretKey: []
paths:
  /v1/balances.list:
    post:
      tags:
        - balances
      description: >-
        Lists individual balances (one row per grant) across customers, live or
        expired: plan balances, standalone balances, top-ups, and pooled
        balances. Pages may hold fewer than `limit` rows while `has_more` is
        true.
      operationId: listBalances
      parameters:
        - name: x-api-version
          in: header
          required: true
          schema:
            type: string
            default: 2.4.0
          x-speakeasy-globals-hidden: true
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                customer_id:
                  type: string
                  description: >-
                    Only return rows for this customer. Omit to list across
                    every customer.
                entity_id:
                  type: string
                  description: Only return rows for this entity. Requires customer_id.
                limit:
                  type: integer
                  minimum: 1
                  maximum: 200
                  default: 50
                  description: Number of items to return. Default 50, hard ceiling 200.
                start_cursor:
                  type: string
                  default: ''
                  description: >-
                    Opaque pagination cursor. Empty string (default) requests
                    the first page; use next_cursor from a prior response for
                    subsequent pages.
                statuses:
                  type: array
                  minItems: 1
                  items:
                    enum:
                      - active
                      - expired
                    type: string
                  description: >-
                    Statuses to include. Defaults to active. A balance is
                    expired when its plan expired, or when a standalone balance
                    passed its expires_at.
                plan_id:
                  anyOf:
                    - type: string
                    - type: 'null'
                  description: >-
                    Only return balances from this plan. Pass null for
                    standalone balances only (top-ups, balances.create,
                    rollovers).
                feature_id:
                  type: string
                  description: Only return balances for this feature.
              title: ListBalancesParams
              examples:
                - customer_id: cus_123
                  statuses:
                    - expired
                - customer_id: cus_123
                  feature_id: messages
                  plan_id: null
            example:
              customer_id: cus_123
              statuses:
                - expired
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  list:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          default: ''
                          description: The unique identifier for this balance breakdown.
                        plan_id:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: >-
                            The plan ID this balance originates from, or null
                            for standalone balances.
                        included_grant:
                          type: number
                          description: Amount granted from the plan's included usage.
                        prepaid_grant:
                          type: number
                          description: Amount granted from prepaid purchases or top-ups.
                        remaining:
                          type: number
                          description: Remaining balance available for use.
                        usage:
                          type: number
                          description: Amount consumed in the current period.
                        unlimited:
                          type: boolean
                          description: Whether this balance has unlimited usage.
                        reset:
                          anyOf:
                            - type: object
                              properties:
                                interval:
                                  anyOf:
                                    - enum:
                                        - one_off
                                        - minute
                                        - hour
                                        - day
                                        - week
                                        - month
                                        - quarter
                                        - semi_annual
                                        - year
                                      type: string
                                    - const: multiple
                                  description: >-
                                    The reset interval (hour, day, week, month,
                                    etc.) or 'multiple' if combined from
                                    different intervals.
                                interval_count:
                                  type: number
                                  description: >-
                                    Number of intervals between resets (eg. 2
                                    for bi-monthly).
                                resets_at:
                                  anyOf:
                                    - type: number
                                    - type: 'null'
                                  description: Timestamp when the balance will next reset.
                              required:
                                - interval
                                - resets_at
                            - type: 'null'
                          description: >-
                            Reset configuration for this balance, or null if no
                            reset.
                        price:
                          anyOf:
                            - type: object
                              properties:
                                amount:
                                  type: number
                                  description: The per-unit price amount.
                                tiers:
                                  type: array
                                  items:
                                    type: object
                                    properties:
                                      to:
                                        anyOf:
                                          - type: number
                                          - const: inf
                                      amount:
                                        type: number
                                      flat_amount:
                                        type: number
                                    required:
                                      - to
                                      - amount
                                  description: Tiered pricing configuration if applicable.
                                tier_behavior:
                                  enum:
                                    - graduated
                                    - volume
                                  type: string
                                  description: >-
                                    How tiers are applied: graduated (split
                                    across bands) or volume (flat rate for the
                                    matched tier).
                                billing_units:
                                  type: number
                                  description: >-
                                    The number of units per billing increment
                                    (eg. $9 / 250 units).
                                billing_method:
                                  enum:
                                    - prepaid
                                    - usage_based
                                  type: string
                                  description: >-
                                    Whether usage is prepaid or billed
                                    pay-per-use.
                                max_purchase:
                                  anyOf:
                                    - type: number
                                    - type: 'null'
                                  description: >-
                                    Maximum quantity that can be purchased, or
                                    null for unlimited.
                              required:
                                - billing_units
                                - billing_method
                                - max_purchase
                            - type: 'null'
                          description: >-
                            Pricing configuration if this balance has
                            usage-based pricing.
                        expires_at:
                          anyOf:
                            - type: number
                            - type: 'null'
                          description: >-
                            Timestamp when this balance expires, or null for no
                            expiration.
                        feature_id:
                          type: string
                          description: The feature this balance is for.
                        status:
                          enum:
                            - active
                            - expired
                          type: string
                          description: Whether this balance is active or expired.
                        rollovers:
                          type: array
                          items:
                            type: object
                            properties:
                              granted:
                                type: number
                                description: >-
                                  Amount originally rolled over from a previous
                                  period, before any of it was consumed.
                              balance:
                                type: number
                                description: >-
                                  Amount of balance rolled over from a previous
                                  period.
                              expires_at:
                                type: number
                                description: Timestamp when the rollover balance expires.
                            required:
                              - granted
                              - balance
                              - expires_at
                          description: Rollover balances carried over onto this balance.
                        customer_id:
                          type: string
                          description: The customer this balance belongs to.
                        entity_id:
                          anyOf:
                            - type: string
                            - type: 'null'
                          description: The entity this balance is scoped to, or null.
                        created_at:
                          type: number
                          description: Timestamp when this balance was created.
                      required:
                        - plan_id
                        - included_grant
                        - prepaid_grant
                        - remaining
                        - usage
                        - unlimited
                        - reset
                        - price
                        - expires_at
                        - feature_id
                        - status
                        - rollovers
                        - customer_id
                        - entity_id
                        - created_at
                    description: Rows on this page.
                  has_more:
                    type: boolean
                    description: >-
                      Whether more results exist. A page may hold fewer than
                      `limit` items (even zero) while `has_more` is true, so
                      paginate until `has_more` is false.
                  next_cursor:
                    anyOf:
                      - type: string
                      - type: 'null'
                    description: >-
                      Pass as start_cursor to fetch the next page. Null when
                      has_more is false.
                required:
                  - list
                  - has_more
                  - next_cursor
                examples:
                  - list:
                      - id: bonus_credits
                        plan_id: null
                        included_grant: 50
                        prepaid_grant: 0
                        remaining: 0
                        usage: 50
                        unlimited: false
                        reset:
                          interval: one_off
                          resets_at: null
                        price: null
                        expires_at: 1771999921437
                        feature_id: messages
                        status: expired
                        rollovers: []
                        customer_id: cus_123
                        entity_id: null
                        created_at: 1769904000000
                    has_more: false
                    next_cursor: null
              example:
                list:
                  - id: bonus_credits
                    plan_id: null
                    included_grant: 50
                    prepaid_grant: 0
                    remaining: 0
                    usage: 50
                    unlimited: false
                    reset:
                      interval: one_off
                      resets_at: null
                    price: null
                    expires_at: 1771999921437
                    feature_id: messages
                    status: expired
                    rollovers: []
                    customer_id: cus_123
                    entity_id: null
                    created_at: 1769904000000
                has_more: false
                next_cursor: null
components:
  securitySchemes:
    secretKey:
      type: http
      scheme: bearer
      bearerFormat: JWT

````