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

# Credits

> Returns the account's remaining API credit balance.

Authenticates with the API key only; no per-service enablement or minimum credit balance is required. When the optional `Api-Origin-Key` header identifies a partner account, the endpoint instead returns a partner usage report aggregating API call counts across every account that shares the partner's custom origin, over the `start_date`/`end_date` range (defaults: beginning of the current month through today). An unknown origin key returns 401 `invalid_origin_key`; a partner account without a configured custom origin returns 400 `no_custom_origin_configured`.

**Billing:** never billed; this endpoint does not consume credits.



## OpenAPI

````yaml GET /api/v1/credits
openapi: 3.0.1
info:
  title: Retention API
  version: v1
  description: Retention.com identity & data resolution APIs.
servers:
  - url: https://api.rb2b.com
security: []
tags:
  - name: Identity
    description: >-
      Core Identity. Resolve a hashed email (or batch) into a shaped person
      profile.
paths:
  /api/v1/credits:
    get:
      tags:
        - Account
      summary: Get remaining API credits
      description: >-
        Returns the account's remaining API credit balance.


        Authenticates with the API key only; no per-service enablement or
        minimum credit balance is required. When the optional `Api-Origin-Key`
        header identifies a partner account, the endpoint instead returns a
        partner usage report aggregating API call counts across every account
        that shares the partner's custom origin, over the
        `start_date`/`end_date` range (defaults: beginning of the current month
        through today). An unknown origin key returns 401 `invalid_origin_key`;
        a partner account without a configured custom origin returns 400
        `no_custom_origin_configured`.


        **Billing:** never billed; this endpoint does not consume credits.
      operationId: getCredits
      parameters:
        - name: Api-Origin-Key
          in: header
          required: false
          schema:
            type: string
          description: >-
            Partner origin key. When present, switches the response to a partner
            usage report covering all accounts that share the partner's custom
            origin. Also accepted as `X-Api-Origin-Key`.
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Start of the partner usage report range (ISO 8601 date, e.g.
            `2026-06-01`). Defaults to the beginning of the current month. Only
            used with `Api-Origin-Key`.
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            End of the partner usage report range (ISO 8601 date, e.g.
            `2026-06-10`). Defaults to today. Only used with `Api-Origin-Key`.
      responses:
        '200':
          description: Credits returned
          content:
            application/json:
              schema:
                type: object
                required:
                  - credits_remaining
                properties:
                  credits_remaining:
                    type: number
                    format: float
                    description: >-
                      API credits currently remaining on the account. (When
                      `Api-Origin-Key` is supplied, the body is a partner usage
                      report instead: `partner_origin`, `date_range`, `summary`,
                      and per-account `accounts` usage breakdowns.)
                    example: 1000
        '401':
          description: Missing, malformed, or unknown API key
          content:
            application/json:
              schema:
                type: object
                required:
                  - error
                properties:
                  error:
                    type: string
                    enum:
                      - missing_api_key
                      - invalid_api_key_format
                      - invalid_api_key
                      - invalid_origin_key
                    description: >-
                      `missing_api_key`: no key supplied.
                      `invalid_api_key_format`: key does not match the expected
                      format. `invalid_api_key`: key does not belong to any
                      account. `invalid_origin_key`: the `Api-Origin-Key` header
                      does not match any partner account.
      security:
        - api_key: []
components:
  securitySchemes:
    api_key:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        Per-account API key. Also accepted as `Api-Key` or `Authorization:
        Bearer <key>`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.