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

# Usage and charges by category

> Usage and what the wallet was charged, split by category and subcategory: voice (outbound calls, inbound calls, branded caller ID), SMS (sent, received, MMS sent, MMS received), email, Quick Agent Actions (AI calls, AI text conversations, single texts, emails), iMessage, AI video, lead enrichment and other. Every subcategory is always listed, zeros included. Defaults to the current usage period; pass `start` and/or `end` (ISO 8601, at most 366 days apart) for any other range. `charged_usd` is what was actually billed, so usage inside the plan's included allowance shows $0. Free: reads are never billed.



## OpenAPI

````yaml /openapi.json get /v1/billing/usage
openapi: 3.1.0
info:
  title: LumisReach v1 API
  version: 1.0.0
  description: >-
    Programmatic access to the LumisReach voice platform — calls, numbers,
    caller trust, and brands.
  contact:
    name: LumisReach
    email: founders@lumisreach.com
servers:
  - url: https://api.lumisreach.com/api
security:
  - bearerAuth: []
tags:
  - name: Phone Numbers
  - name: Caller IDs
  - name: Enterprise Registration
  - name: Branded Calling
  - name: Calls
  - name: SMS
  - name: WebRTC
  - name: Reputation
  - name: Usage
  - name: Account
  - name: Billing
  - name: Conversation History
  - name: Documents
  - name: Lincoln AI
  - name: Quick Agent Actions
  - name: Sub-entities
paths:
  /v1/billing/usage:
    get:
      tags:
        - Billing
      summary: Usage and charges by category
      description: >-
        Usage and what the wallet was charged, split by category and
        subcategory: voice (outbound calls, inbound calls, branded caller ID),
        SMS (sent, received, MMS sent, MMS received), email, Quick Agent Actions
        (AI calls, AI text conversations, single texts, emails), iMessage, AI
        video, lead enrichment and other. Every subcategory is always listed,
        zeros included. Defaults to the current usage period; pass `start`
        and/or `end` (ISO 8601, at most 366 days apart) for any other range.
        `charged_usd` is what was actually billed, so usage inside the plan's
        included allowance shows $0. Free: reads are never billed.
      operationId: v1_billing_usage_get
      parameters:
        - name: start
          in: query
          required: false
          schema:
            description: >-
              Inclusive start (ISO 8601). Defaults to the start of the current
              usage period.
            type: string
        - name: end
          in: query
          required: false
          schema:
            description: >-
              Exclusive end (ISO 8601). Defaults to the end of the current
              period, or now when `start` is set.
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $schema: http://json-schema.org/draft-07/schema#
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      start:
                        type: string
                      end:
                        type: string
                      currency:
                        type: string
                        const: USD
                      total_charged_usd:
                        type: number
                      credits_added_usd:
                        type: object
                        properties:
                          total:
                            type: number
                          by_source:
                            type: object
                            propertyNames:
                              type: string
                            additionalProperties:
                              type: number
                            description: >-
                              purchase, auto_recharge, plan_included, transfer,
                              committed_budget
                        required:
                          - total
                          - by_source
                        additionalProperties: false
                      categories:
                        type: array
                        items:
                          type: object
                          properties:
                            category:
                              type: string
                              enum:
                                - voice
                                - sms
                                - email
                                - quick_actions
                                - imessage
                                - ai_video
                                - lead_enrichment
                                - other
                            label:
                              type: string
                            charged_usd:
                              type: number
                            subcategories:
                              type: array
                              items:
                                type: object
                                properties:
                                  subcategory:
                                    type: string
                                  label:
                                    type: string
                                  count:
                                    type: number
                                    description: Calls, messages, renders or charges
                                  quantity:
                                    type: number
                                    description: Amount used, in `unit`
                                  unit:
                                    type: string
                                  charged_usd:
                                    type: number
                                    description: >-
                                      What the wallet was billed. Usage inside
                                      the plan's included allowance is $0.
                                required:
                                  - subcategory
                                  - label
                                  - count
                                  - quantity
                                  - unit
                                  - charged_usd
                                additionalProperties: false
                          required:
                            - category
                            - label
                            - charged_usd
                            - subcategories
                          additionalProperties: false
                    required:
                      - start
                      - end
                      - currency
                      - total_charged_usd
                      - credits_added_usd
                      - categories
                    additionalProperties: false
                required:
                  - data
                additionalProperties: false
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: Conflict (incl. idempotency conflicts)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
components:
  schemas:
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
            message:
              type: string
            fields:
              type: object
              additionalProperties:
                type: string
            doc_url:
              type: string
              format: uri
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````