> ## 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.

# Cost events

> The individual metered events behind the totals, newest first. Match `request_id` against the `meta.request_id` of the call that produced it.

Requires the `usage:read` scope.



## OpenAPI

````yaml /openapi.json get /v1/usage/costs
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/costs:
    get:
      tags:
        - Account
      summary: Cost events
      description: >-
        The individual metered events behind the totals, newest first. Match
        `request_id` against the `meta.request_id` of the call that produced it.


        Requires the `usage:read` scope.
      operationId: usageCosts
      parameters:
        - name: limit
          in: query
          required: false
          description: Events to return, 1–500.
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 100
      responses:
        '200':
          description: Cost events.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      events:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: integer
                            request_id:
                              type: string
                              format: uuid
                            operation:
                              type: string
                              examples:
                                - data.people.profile
                            funding_source:
                              $ref: '#/components/schemas/FundingSource'
                            acquisition_units:
                              type: integer
                            billable_units:
                              type: integer
                            billable_amount_usd:
                              type: number
                            created_at:
                              type: string
                              format: date-time
                  meta:
                    $ref: '#/components/schemas/Meta'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/InsufficientScope'
        '429':
          $ref: '#/components/responses/RateLimited'
      security:
        - bearerAuth: []
components:
  schemas:
    FundingSource:
      type: string
      enum:
        - platform
        - workspace_byok
      description: >-
        `platform` means Revcenter's own provider keys paid for the call and it
        counts as billable acquisition. `workspace_byok` means your workspace's
        own provider key did — the activity is recorded, but the vendor spend is
        yours, not billable overage.
    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.

````