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

# Check the points balance

> Returns the points balance of the workspace behind the API key: `available` to spend now, `reserved` by in-flight operations, and the lifetime `granted` total. Call this before submitting a batch of lookups rather than discovering mid-run that the workspace ran out.

#### Billing

Free — this endpoint does not consume points.



## OpenAPI

````yaml /openapi.json get /api/v1/points
openapi: 3.1.0
info:
  title: Loice API
  version: v1
  description: >-
    The Loice API finds and verifies professional contact data. Every capability
    is exposed here, key-authenticated and rate-limited; the web app is a client
    of the same platform.


    **Authentication** — pass your workspace API key on every request (except
    the API description) as `Authorization: Bearer loice_sk_…`. Keys are created
    under Settings → API Keys.


    **Billing** — operations are billed in points against your workspace
    balance. Each operation below states when the charge applies. The current
    cost of every operation is shown in the app under [Settings →
    Billing](https://app.loice.ai/settings/account?tab=billing) and in the live
    API description, `GET /api/v1/openapi.json`. Calls that fail because of a
    system or provider error (timeouts, upstream failures, our defects) are not
    billed, and rate-limited calls are rejected before any billable work. Check
    headroom with `GET /api/v1/points`. Where an operation documents an
    `Idempotency-Key` header, send one to retry safely: a repeated request
    returns the original outcome and is not charged again.


    **Errors** — every non-200 response has the shape `{ "error": { "message":
    "…" } }`. Operations whose error responses document an `error.code` also
    return that machine-readable code beside the message; branch on the code,
    not the text.
servers:
  - url: https://app.loice.ai
security: []
paths:
  /api/v1/points:
    get:
      summary: Check the points balance
      description: >-
        Returns the points balance of the workspace behind the API key:
        `available` to spend now, `reserved` by in-flight operations, and the
        lifetime `granted` total. Call this before submitting a batch of lookups
        rather than discovering mid-run that the workspace ran out.


        #### Billing


        Free — this endpoint does not consume points.
      responses:
        '200':
          description: The current balance.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      available:
                        type: integer
                      reserved:
                        type: integer
                      granted:
                        type: integer
                    required:
                      - available
                      - reserved
                      - granted
                required:
                  - data
              example:
                data:
                  available: 99
                  reserved: 0
                  granted: 100
        '401':
          description: >-
            API key missing (`Missing API key. Pass it as: Authorization: Bearer
            <key>`), invalid (`Invalid API key`), or expired (`This API key has
            expired`).
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                    required:
                      - message
                required:
                  - error
        '405':
          description: Method not allowed — see the `Allow` response header.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                    required:
                      - message
                required:
                  - error
        '429':
          description: >-
            Rate limit exceeded for this workspace. Retry after the number of
            seconds in the `Retry-After` header (60). Rate-limited calls are
            never billed.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      message:
                        type: string
                    required:
                      - message
                required:
                  - error
        '500':
          description: '`internal_error`: the balance read failed on our side.'
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        enum:
                          - validation_error
                          - unauthenticated
                          - not_found
                          - forbidden
                          - method_not_allowed
                          - idempotency_conflict
                          - idempotency_in_progress
                          - rate_limited
                          - internal_error
                          - run_already_active
                          - search_unavailable
                          - invalid_continuation
                        description: >-
                          Machine-readable error code. Branch on this, not on
                          `message`.
                      message:
                        type: string
                        description: Human-readable explanation.
                      retryAfterSeconds:
                        type: integer
                        description: >-
                          Present on a 429 only: seconds until the workspace may
                          call again (same value as the `Retry-After` header).
                    required:
                      - code
                      - message
                required:
                  - error
      security:
        - workspaceApiKey: []
components:
  securitySchemes:
    workspaceApiKey:
      type: http
      scheme: bearer
      description: >-
        Workspace API key (`loice_sk_` + 48 hex characters), created under
        Settings → API Keys. Sent as `Authorization: Bearer loice_sk_…`.
        Invalid, missing, or expired keys are rejected with 401 before any
        billable work happens.

````

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