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

# Get account usage

> Authenticated account plan, spendable credits and UTC monthly period.

```bash theme={null}
curl 'https://mcp.enricho.co/api/billing/usage' \
  -H 'Authorization: Bearer enr_YOUR_API_KEY'
```

No input is required; no credits are consumed. The API key determines the account.

* `plan`: current account plan.
* `credits_limit`: monthly allowance, excluding purchased top-ups.
* `monthly_credits_remaining`: unused credits for the calendar month.
* `topup_credits`: purchased balance, not reset at month boundaries.
* `credits_remaining`: monthly remaining plus top-ups.
* `period_start`, `period_end`: start of this and next calendar month, UTC.

Read usage before a large full page and after payment confirmation. A balance read does not reserve credits: concurrent requests can spend them before search settlement. After an unconfirmed search charge or lost response, inspect usage before retrying, since retries can incur another debit.


## OpenAPI

````yaml api-reference/openapi.json GET /api/billing/usage
openapi: 3.1.0
info:
  title: Enricho Public REST API
  version: 1.0.0
  description: >-
    Public directory search and billing APIs. Full search costs 1 credit per
    returned record; previews and usage calls use no credits. Request and
    response contracts reflect the current public gateway and service handlers.
servers:
  - url: https://mcp.enricho.co
security:
  - apiKey: []
  - headerKey: []
tags:
  - name: Directory
  - name: Billing
paths:
  /api/billing/usage:
    get:
      tags:
        - Billing
      summary: Get account credit usage
      description: >-
        Free. Returns the authenticated account’s balance and UTC monthly
        period. No user_id parameter is accepted as an account selector.
      operationId: getUsage
      responses:
        '200':
          description: Success envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  result:
                    $ref: '#/components/schemas/Usage'
                  message:
                    type: string
                required:
                  - success
                  - result
                  - message
              example:
                success: true
                result:
                  plan: free
                  credits_limit: 100
                  credits_remaining: 90
                  monthly_credits_remaining: 90
                  topup_credits: 0
                  period_start: '2026-10-01T00:00:00Z'
                  period_end: '2026-11-01T00:00:00Z'
                message: Credit usage loaded.
        '401':
          description: 'unauthorized: missing, invalid or revoked API key.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: >-
            rate_limited: key, account or client-IP request limit exceeded; wait
            a minute before retrying.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 'internal: unexpected server failure.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 'upstream_unavailable: gateway could not reach the service.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: >-
            upstream_unavailable: authentication or service dependency
            unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Usage:
      type: object
      properties:
        plan:
          type: string
          description: Current account plan.
        credits_limit:
          type: integer
          description: Monthly plan credit allowance; excludes top-ups.
        credits_remaining:
          type: integer
          description: 'Total spendable credits: monthly_credits_remaining + topup_credits.'
        monthly_credits_remaining:
          type: integer
          description: >-
            Unused monthly credits; reset on the first of each calendar month
            UTC.
        topup_credits:
          type: integer
          description: >-
            Purchased credits remaining. Never expire; used after monthly
            credits.
        period_start:
          type: string
          format: date-time
          description: Start of this calendar month, UTC.
        period_end:
          type: string
          format: date-time
          description: Start of the next calendar month, UTC.
      required:
        - plan
        - credits_limit
        - credits_remaining
        - monthly_credits_remaining
        - topup_credits
        - period_start
        - period_end
    Error:
      type: object
      properties:
        success:
          type: boolean
          const: false
        result:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code.
          required:
            - code
        message:
          type: string
          description: Human-readable error; do not parse this as a stable identifier.
      required:
        - success
        - result
        - message
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: Enricho API key (enr_...)
    headerKey:
      type: apiKey
      in: header
      name: X-Api-Key
      description: >-
        An Enricho API key (enr_...). Use this or Authorization: Bearer, not
        both.

````

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