> ## 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 usage history

> Daily UTC credit consumption and per-feature aggregates.

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

Free. `days` defaults to 30; unparseable query values also use 30. Integers below 7 clamp to 7; above 90 clamp to 90. The period includes today in UTC.

`result.days` contains date/credit pairs in chronological order, including zero-use days. `result.by_feature` maps feature names, such as `people_search` and `companies_search`, to used credits. Keys are not a fixed enumeration. `result.total` is consumption over the selected period, not the remaining balance. This endpoint returns an aggregate, not a per-request audit log, and has no cursor pagination.


## OpenAPI

````yaml api-reference/openapi.json GET /api/billing/usage/history
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/history:
    get:
      tags:
        - Billing
      summary: Get usage history
      description: >-
        Free. Last N UTC calendar days including today; zero-usage days are
        included.
      operationId: getUsageHistory
      parameters:
        - name: days
          in: query
          required: false
          schema:
            type: integer
            default: 30
          description: >-
            Clamped to 7–90 rather than rejected. Omitted or unparseable input
            uses 30.
      responses:
        '200':
          description: Success envelope.
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                    const: true
                  result:
                    $ref: '#/components/schemas/UsageHistory'
                  message:
                    type: string
                required:
                  - success
                  - result
                  - message
        '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:
    UsageHistory:
      type: object
      properties:
        days:
          type: array
          items:
            $ref: '#/components/schemas/DayUsage'
          description: Daily totals in UTC date order, including zero-usage days and today.
        by_feature:
          type: object
          additionalProperties:
            type: integer
          description: >-
            Credit totals by feature, such as people_search and
            companies_search; keys are not a fixed enumeration.
        total:
          type: integer
          description: Credits used over the selected period; not the account balance.
      required:
        - days
        - by_feature
        - total
    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
    DayUsage:
      type: object
      properties:
        date:
          type: string
        credits:
          type: integer
      required:
        - date
        - credits
  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.