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

# Read the account’s balance

> Body: none; any body is ignored.

Returns the account’s balance in tokens: what is available, what is held for calls still running, and whether the balance is low.

A body that is not valid JSON is still answered `400 invalid_body`.

See also [Billing](/api/billing).



## OpenAPI

````yaml POST /v1/balance
openapi: 3.1.0
info:
  title: Orbb API
  version: v1
  description: >-
    Who knows whom, and how well: the people connected to a person, the
    connection between two people, and the person behind an email or a name.
    Every call is a `POST` with a JSON body, except `GET /v1/openapi.json`.


    Read [Authentication](/api/authentication), [Errors](/api/errors),
    [Jobs](/api/jobs), [Billing](/api/billing) and [Rate
    limits](/api/rate-limits) before your first integration.
servers:
  - url: https://api.orbb.com
    description: Production
security:
  - bearer: []
paths:
  /v1/balance:
    post:
      summary: Read the account’s balance
      description: >-
        Body: none; any body is ignored.


        Returns the account’s balance in tokens: what is available, what is held
        for calls still running, and whether the balance is low.


        A body that is not valid JSON is still answered `400 invalid_body`.


        See also [Billing](/api/billing).
      operationId: balance
      responses:
        '200':
          description: The account’s balance.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BalanceAnswer'
              example:
                available: 996.998
                reserved: 0.004
                low_balance: false
        '400':
          description: >-
            Bad Request.


            - `invalid_body`: The body could not be parsed (not valid JSON,
            larger than 16 kB, or not received in full), or does not match the
            operation’s body. See [Errors](/api/errors). Fix the body. `detail`
            names the field when there is one.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: >-
            Unauthorized.


            - `invalid_session`: A token in the form of a session token (three
            parts separated by dots) was refused: expired, or not a session of
            the console. Sign in to the console again, or use an API key.


            - `invalid_api_key`: The `Authorization` header is missing or is not
            `Bearer <token>`, or the key is unknown, revoked or expired. The
            answer is the same whatever the reason. Check the key, or create a
            new one in the console.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            Too Many Requests.


            - `rate_limited`: The account made more calls in the last minute
            than `RateLimit-Limit` allows. Wait `Retry-After` seconds, then
            repeat the same request.


            - `too_many_concurrent`: The account has too many calls waiting for
            an answer at once. Wait for a call to be answered, or `Retry-After`
            seconds, then repeat the same request.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
            Retry-After:
              $ref: '#/components/headers/Retry-After'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            Service Unavailable.


            - `unavailable`: The API could not complete the call, or could not
            check the token or the rate limits. Repeat the same request, backing
            off.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            RateLimit-Limit:
              $ref: '#/components/headers/RateLimit-Limit'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  headers:
    X-Request-Id:
      description: >-
        The id of the request. Every answer carries it; an error body repeats it
        as `request_id`. See Request ids.
      schema:
        type: string
    RateLimit-Limit:
      description: >-
        The calls the account may make per minute. On every answer past
        authentication: not on a `401`, nor on a `400 invalid_body` for a body
        that could not be parsed. See Rate limits.
      schema:
        type: integer
    Retry-After:
      description: The seconds to wait before calling again. On every `429`.
      schema:
        type: integer
  schemas:
    BalanceAnswer:
      type: object
      properties:
        available:
          description: >-
            The tokens the account can spend, not counting those reserved. An
            account with no balance yet reads 0.
          type: number
        reserved:
          description: >-
            The tokens held for calls still running. See
            [Billing](/api/billing).
          type: number
        low_balance:
          description: True when `available` is below 25 tokens.
          type: boolean
      required:
        - available
        - reserved
        - low_balance
    Error:
      type: object
      properties:
        error:
          description: 'The error code. Stable: branch on it.'
          type: string
          enum:
            - invalid_body
            - invalid_session
            - invalid_api_key
            - invalid_limit
            - invalid_types
            - invalid_min_strength
            - invalid_cursor
            - same_person
            - person_not_found
            - ambiguous_person
            - result_unavailable
            - not_found
            - too_many_keys
            - unavailable
            - rate_limited
            - too_many_concurrent
            - research_busy
            - insufficient_balance
            - invalid_max_tokens
            - billing_account_missing
        detail:
          description: >-
            A sentence that explains the error, for a person to read. Its
            wording can change: do not parse it.
          type: string
        request_id:
          description: The id of the request, the same as the `X-Request-Id` header.
          type: string
        candidates:
          description: 'With `422 ambiguous_person` only: every person the id matched.'
          type: array
          items:
            type: object
            properties:
              key:
                description: >-
                  The person’s key: the public identifier percent-decoded and
                  lower-cased. Two people in the answers are the same person
                  when their keys are equal.
                type: string
              publicId:
                description: >-
                  The person’s current LinkedIn public identifier, the part
                  after `/in/` of the profile URL. It is a valid `id`, `a`, `b`
                  or `target` in any call. For a person with no known profile,
                  the identifier as the call gave it, in the form of `key`.
                type: string
              full_name:
                description: The person’s name. Absent when no known profile carries one.
                type: string
              role:
                description: >-
                  The title of the person’s current position; without one, the
                  profile’s headline. Absent when the profile has neither, or no
                  profile is known.
                type: string
              company:
                description: >-
                  The name of the company of the current position shown. Absent
                  when unknown.
                type: string
              companyPublicId:
                description: >-
                  The LinkedIn page of that company, as `company/<slug>`, or
                  `showcase/<slug>` for a showcase page. Absent when unknown.
                type: string
            required:
              - key
              - publicId
      required:
        - error
        - detail
        - request_id
  securitySchemes:
    bearer:
      type: http
      scheme: bearer
      description: >-
        An API key, `orbb_sk_…`, created in the console; or the console’s
        session token. See Authentication.

````

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