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

# Usage totals

> Lifetime totals for every API-key request in the workspace. App activity is excluded — only calls made with an API key are counted.

Requires the `usage:read` scope.



## OpenAPI

````yaml /openapi.json get /v1/usage
openapi: 3.1.0
info:
  title: Revcenter API
  description: >-
    Search, enrich, and activate people and companies. Two authentication
    surfaces share one host: the bearer-token API under `/v1` for
    server-to-server and agent use, and the workspace-session API under `/api`
    that the Revcenter app itself runs on.
  version: '2026-08-12'
servers:
  - url: https://api.revcenter.ai
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Search
    description: Web search, search runs, results, exports, and shareable shortlists.
  - name: People
    description: Person search, profile enrichment, and the workspace contact pool.
  - name: Companies
    description: Company search, company enrichment, and org-chart people.
  - name: Campaigns
    description: Plan, publish, and launch outbound sequences on Smartlead and HeyReach.
  - name: Account
    description: Health, usage totals, and cost events.
paths:
  /v1/usage:
    get:
      tags:
        - Account
      summary: Usage totals
      description: >-
        Lifetime totals for every API-key request in the workspace. App activity
        is excluded — only calls made with an API key are counted.


        Requires the `usage:read` scope.
      operationId: usageTotals
      responses:
        '200':
          description: Aggregate usage.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      requests:
                        type: integer
                        examples:
                          - 1842
                      acquisition_units:
                        type: integer
                        description: Blended Revcenter Acquisition Units.
                        examples:
                          - 18420000
                      billable_units:
                        type: integer
                        examples:
                          - 18420000
                      billable_amount_usd:
                        type: number
                        examples:
                          - 92.1
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
components:
  schemas:
    Meta:
      type: object
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Echoes an inbound `X-Request-Id` when you send one, otherwise
            generated. Always returned in the `X-Request-Id` header too.
    Error:
      type: object
      description: The error shape used by every `/v1` endpoint.
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              examples:
                - insufficient_scope
            message:
              type: string
            details:
              type: object
              additionalProperties: true
        meta:
          $ref: '#/components/schemas/Meta'
  responses:
    Unauthorized:
      description: No key, or the key is invalid, expired, or revoked.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            missing:
              value:
                error:
                  code: missing_api_key
                  message: 'Send Authorization: Bearer rvc_live_...'
                meta:
                  request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33
            invalid:
              value:
                error:
                  code: invalid_api_key
                  message: API key is invalid, expired, or revoked.
                meta:
                  request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33
    InsufficientScope:
      description: The key authenticated but lacks the scope this endpoint requires.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            scope:
              value:
                error:
                  code: insufficient_scope
                  message: API key requires scope 'data:people:read'.
                meta:
                  request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33
    RateLimited:
      description: >-
        The key exceeded its per-minute limit. Check `X-RateLimit-Reset` for
        when the window rolls over.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            limited:
              value:
                error:
                  code: rate_limited
                  message: API key rate limit exceeded.
                meta:
                  request_id: 6f1c2b7e-9a3d-4c5f-8e21-0b7d4a9c1e33
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        A Revcenter API key: `Authorization: Bearer rvc_live_...`. Keys are
        scoped, rate limited per key, and metered per workspace.

````