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

# Get usage

> Aggregate the org's memory usage for the current quota period — a
calendar month, or your billing period on plans that meter per billing
period — plus a per-day breakdown if requested, plus an inline storage
snapshot.

- ``operations`` totals ``messages_ingested`` / ``searches`` /
  ``requests`` across every API key for the period.
- ``quota.monthly`` pairs those totals against the plan caps
  resolved from the org's subscription tier; ``limit: null`` means
  the tier is uncapped (enterprise).
- ``quota.rate_limit_req_per_min`` is the per-API-key request
  ceiling enforced across all memory endpoints.



## OpenAPI

````yaml https://api.staging.xtrace.ai/openapi.public.json get /v1/usage
openapi: 3.1.0
info:
  title: XTrace Vec DB
  description: XTrace API
  version: 1.0.0
servers:
  - url: https://api.production.xtrace.ai
    description: Production
security:
  - ApiKeyHeader: []
  - BearerToken: []
paths:
  /v1/usage:
    get:
      tags:
        - usage
      summary: Get usage
      description: |-
        Aggregate the org's memory usage for the current quota period — a
        calendar month, or your billing period on plans that meter per billing
        period — plus a per-day breakdown if requested, plus an inline storage
        snapshot.

        - ``operations`` totals ``messages_ingested`` / ``searches`` /
          ``requests`` across every API key for the period.
        - ``quota.monthly`` pairs those totals against the plan caps
          resolved from the org's subscription tier; ``limit: null`` means
          the tier is uncapped (enterprise).
        - ``quota.rate_limit_req_per_min`` is the per-API-key request
          ceiling enforced across all memory endpoints.
      operationId: get_usage_v1_usage_get
      parameters:
        - name: daily
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include the per-day ``daily[]`` array (one entry per calendar day
              in the period). Off by default to keep the response cheap; the
              dashboard chart opts in.
            default: false
            title: Daily
          description: >-
            Include the per-day ``daily[]`` array (one entry per calendar day in
            the period). Off by default to keep the response cheap; the
            dashboard chart opts in.
        - name: by_api_key
          in: query
          required: false
          schema:
            type: boolean
            description: >-
              Include the per-API-key breakdown with each key's ``name`` /
              ``first_n`` display fields. Off by default — adds extra lookups.
            default: false
            title: By Api Key
          description: >-
            Include the per-API-key breakdown with each key's ``name`` /
            ``first_n`` display fields. Off by default — adds extra lookups.
        - name: org_id
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Org Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    UsageResponse:
      properties:
        object:
          type: string
          const: usage
          title: Object
          default: usage
        as_of:
          type: string
          title: As Of
          description: When this snapshot was computed.
        period:
          $ref: '#/components/schemas/Period'
        tier:
          anyOf:
            - type: string
            - type: 'null'
          title: Tier
          description: The org's subscription tier; ``None`` if unset.
        operations:
          $ref: '#/components/schemas/Operations'
        daily:
          anyOf:
            - items:
                $ref: '#/components/schemas/DailyEntry'
              type: array
            - type: 'null'
          title: Daily
          description: >-
            ``None`` when ``?daily=false`` (default); populated when
            ``?daily=true``.
        by_api_key:
          anyOf:
            - items:
                $ref: '#/components/schemas/ByApiKeyEntry'
              type: array
            - type: 'null'
          title: By Api Key
          description: >-
            ``None`` when ``?by_api_key=false`` (default); populated when
            ``?by_api_key=true``.
        storage:
          $ref: '#/components/schemas/StorageSnapshot'
        quota:
          $ref: '#/components/schemas/Quota'
      type: object
      required:
        - as_of
        - period
        - storage
        - quota
      title: UsageResponse
      description: Top-level shape for ``GET /v1/usage``.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Period:
      properties:
        key:
          type: string
          title: Key
          description: >-
            Period identifier — ``YYYY-MM`` for ``calendar_month``, or the
            period's start date ``YYYY-MM-DD`` for ``billing_period``.
        start:
          type: string
          title: Start
        end:
          type: string
          title: End
        type:
          type: string
          enum:
            - calendar_month
            - billing_period
          title: Type
          default: calendar_month
      type: object
      required:
        - key
        - start
        - end
      title: Period
    Operations:
      properties:
        messages_ingested:
          type: integer
          title: Messages Ingested
          description: >-
            Chat messages ingested via POST /v1/memories — the sum of payload
            message counts, not request count and not the memories extracted
            from them.
          default: 0
        searches:
          type: integer
          title: Searches
          description: POST /v1/memories/search calls (one search per call).
          default: 0
        requests:
          type: integer
          title: Requests
          description: Total metered memory API calls (ingest + search).
          default: 0
      type: object
      title: Operations
      description: Period-total memory operation counters for the org.
    DailyEntry:
      properties:
        date:
          type: string
          title: Date
          description: Calendar day in ``YYYY-MM-DD`` form.
        messages_ingested:
          type: integer
          title: Messages Ingested
          default: 0
        searches:
          type: integer
          title: Searches
          default: 0
        requests:
          type: integer
          title: Requests
          default: 0
      type: object
      required:
        - date
      title: DailyEntry
      description: One row in the ``daily[]`` array — chart x-axis points.
    ByApiKeyEntry:
      properties:
        api_key_hash:
          type: string
          title: Api Key Hash
        first_n:
          anyOf:
            - type: string
            - type: 'null'
          title: First N
          description: Display prefix of the API key.
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: Human-readable label for the API key.
        messages_ingested:
          type: integer
          title: Messages Ingested
          default: 0
        searches:
          type: integer
          title: Searches
          default: 0
        requests:
          type: integer
          title: Requests
          default: 0
        last_used_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Last Used At
          description: >-
            Most recent ``updatedAt`` across this key's memory rollup rows for
            the period. ``None`` until the key has any usage.
      type: object
      required:
        - api_key_hash
      title: ByApiKeyEntry
      description: One row in the ``by_api_key[]`` breakdown.
    StorageSnapshot:
      properties:
        memories_active:
          type: integer
          title: Memories Active
          default: 0
        episodes_active:
          type: integer
          title: Episodes Active
          default: 0
        artifacts_active:
          type: integer
          title: Artifacts Active
          default: 0
        as_of:
          type: string
          title: As Of
      type: object
      required:
        - as_of
      title: StorageSnapshot
      description: |-
        Currently-active per-type row counts.

        Cached harder than operations (computing the counts is expensive);
        ``as_of`` reflects the mint time of the cached snapshot and may
        lag the response-level ``as_of``.
    Quota:
      properties:
        rate_limit_req_per_min:
          type: integer
          title: Rate Limit Req Per Min
          description: Per-API-key request ceiling across all memory endpoints.
        monthly:
          $ref: '#/components/schemas/MemoryMonthlyQuota'
      type: object
      required:
        - rate_limit_req_per_min
        - monthly
      title: Quota
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    MemoryMonthlyQuota:
      properties:
        period_key:
          type: string
          title: Period Key
          description: >-
            Identifier for the current quota period — ``YYYY-MM`` for a calendar
            month, or the period's start date ``YYYY-MM-DD`` for a billing
            period.
        resets_at:
          type: string
          title: Resets At
          description: >-
            ISO-8601 UTC instant when the quota counters reset (the start of the
            next calendar month, or the end of the current billing period).
        messages_ingested:
          $ref: '#/components/schemas/QuotaCounter'
        searches:
          $ref: '#/components/schemas/QuotaCounter'
      type: object
      required:
        - period_key
        - resets_at
      title: MemoryMonthlyQuota
      description: |-
        Quota state for the current period — a calendar month, or your billing
        period on plans that meter per billing period.
    QuotaCounter:
      properties:
        used:
          type: integer
          title: Used
          description: Consumed so far in the current quota period.
          default: 0
        limit:
          anyOf:
            - type: integer
            - type: 'null'
          title: Limit
          description: Cap for the org's plan; ``null`` = unlimited (enterprise).
      type: object
      title: QuotaCounter
      description: 'One metered quota dimension: amount used vs the plan cap.'
  securitySchemes:
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key
      description: 'Long-lived org API key. Alternative: `Authorization: Bearer <key>`.'
    BearerToken:
      type: http
      scheme: bearer
      bearerFormat: Token
      description: 'Long-lived API key sent as `Authorization: Bearer <api-key>`.'

````