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

# Get credits

> Every credit your organization has been granted and how much of it has been used. `total_credits` minus `total_usage` is what remains. Figures can trail recent usage by a few minutes.



## OpenAPI

````yaml /openapi/management.yaml get /credits
openapi: 3.1.0
info:
  title: Pearl Management API
  version: '1.0'
  description: >-
    Read your organization's credits and usage with a management key, and let
    any API key describe itself. The Management API never runs inference: model
    requests go to the Inference API, with an inference key.
servers:
  - url: https://api.platform.pearlresearch.ai/api/v1
security:
  - managementKey: []
tags:
  - name: Credits
    description: The credits granted to your organization and how much of them is used.
  - name: API keys
    description: The limit, expiration, and spend of the key that calls.
  - name: Activity
    description: Daily usage per model.
paths:
  /credits:
    get:
      tags:
        - Credits
      summary: Get credits
      description: >-
        Every credit your organization has been granted and how much of it has
        been used. `total_credits` minus `total_usage` is what remains. Figures
        can trail recent usage by a few minutes.
      operationId: getCredits
      responses:
        '200':
          description: The organization's credit totals.
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                properties:
                  data:
                    $ref: '#/components/schemas/Credits'
              example:
                data:
                  total_credits: 150
                  total_usage: 61.348217
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/ManagementKeyRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
        '503':
          $ref: '#/components/responses/CreditsUnavailable'
      x-codeSamples:
        - lang: bash
          label: cURL
          source: |
            curl "https://api.platform.pearlresearch.ai/api/v1/credits" \
              -H "Authorization: Bearer $PEARL_MANAGEMENT_KEY"
        - lang: python
          label: Python
          source: |
            import os
            import requests

            response = requests.get(
                "https://api.platform.pearlresearch.ai/api/v1/credits",
                headers={"Authorization": f"Bearer {os.environ['PEARL_MANAGEMENT_KEY']}"},
            )
            response.raise_for_status()
            credits = response.json()["data"]
            print(credits["total_credits"] - credits["total_usage"])
        - lang: typescript
          label: TypeScript
          source: >
            const response = await
            fetch("https://api.platform.pearlresearch.ai/api/v1/credits", {
              headers: {Authorization: `Bearer ${process.env.PEARL_MANAGEMENT_KEY}`},
            });

            if (!response.ok) throw new Error((await
            response.json()).error.message);

            const {data} = await response.json();

            console.log(data.total_credits - data.total_usage);
components:
  headers:
    X-RateLimit-Limit:
      description: Requests allowed per minute.
      schema:
        type: integer
      example: 10
    X-RateLimit-Remaining:
      description: Requests left in the current minute.
      schema:
        type: integer
      example: 9
    X-RateLimit-Reset:
      description: When the current minute's window ends, as a Unix timestamp in seconds.
      schema:
        type: integer
      example: 1763294460
    Retry-After:
      description: >-
        Seconds until the current window ends. Wait at least that long before
        retrying.
      schema:
        type: integer
      example: 37
  schemas:
    Credits:
      type: object
      required:
        - total_credits
        - total_usage
      properties:
        total_credits:
          type: number
          description: >-
            USD of every credit granted to your organization: top-ups,
            auto-recharges, the welcome credit, cashback, and credits from
            Pearl.
        total_usage:
          type: number
          description: >-
            USD of those credits already used. Usage billed on an invoice
            instead of paid from credits is not included.
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: integer
              description: The HTTP status code.
            message:
              type: string
              description: What went wrong.
  responses:
    Unauthorized:
      description: >-
        A missing, unknown, revoked, or expired key. Retrying with the same key
        fails again.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              summary: No key
              value:
                error:
                  code: 401
                  message: 'Missing API key. Send it as Authorization: Bearer <key>.'
            invalid:
              summary: Unknown key
              value:
                error:
                  code: 401
                  message: Invalid API key.
            revoked:
              summary: Revoked key
              value:
                error:
                  code: 401
                  message: This API key has been revoked.
            expired:
              summary: Expired key
              value:
                error:
                  code: 401
                  message: This API key has expired.
    ManagementKeyRequired:
      description: An inference key, which can only call `GET /key`. Use a management key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 403
              message: >-
                This endpoint needs a management key (sk-prl-mgmt-...).
                Inference keys can only call GET /key.
    RateLimited:
      description: >-
        Rate limit exceeded: 10 requests per minute. Wait `Retry-After` seconds
        before retrying.
      headers:
        Retry-After:
          $ref: '#/components/headers/Retry-After'
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 429
              message: Rate limit exceeded. Please try again later.
    InternalError:
      description: Unexpected server error. Safe to retry with backoff.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: 500
              message: Internal server error.
    CreditsUnavailable:
      description: >-
        Credits can't be read right now: a new organization is still being set
        up, or the billing system is unavailable. Retry after a few seconds.
      headers:
        X-RateLimit-Limit:
          $ref: '#/components/headers/X-RateLimit-Limit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/X-RateLimit-Remaining'
        X-RateLimit-Reset:
          $ref: '#/components/headers/X-RateLimit-Reset'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            unavailable:
              summary: Billing system unavailable
              value:
                error:
                  code: 503
                  message: Credits are temporarily unavailable. Try again shortly.
            settingUp:
              summary: New organization
              value:
                error:
                  code: 503
                  message: >-
                    Credits are not available yet: the organization is still
                    being set up. Try again shortly.
  securitySchemes:
    managementKey:
      type: http
      scheme: bearer
      description: >-
        `Bearer` followed by a management key (`sk-prl-mgmt-`). Org admins
        create them on the [Management
        Keys](https://platform.pearlresearch.ai/management-keys) page. An
        inference key gets a `403`.

````

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