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

# Retrieve instance usage analytics.

> 
    ROLES: INSTANCE_ADMIN
    USER: true
    SERVICE ACCOUNT: true

    Assistant analytics use the same selected UTC period across totals, model,
    account, and daily-series views. The lower bound is inclusive and the upper
    bound is exclusive. Omit both bounds for the current UTC month through now.
    



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/config/instance/usage
openapi: 3.0.0
info:
  title: RevoEngine Platform API
  description: Official RevoEngine Platform API documentation.
  version: 1.3.0
  contact:
    name: Support
    email: support@revoengine.com
  termsOfService: https://docs.revoengine.com/tos
servers:
  - url: https://api.revoengine.com
    description: Production
security: []
tags:
  - name: Accounts
    description: Users, service accounts, API keys, status, and platform access.
    externalDocs:
      description: Identity and access guide
      url: https://docs.revoengine.com/operate/identity-and-access
  - name: Activity
    description: Snapshot-backed activity and version history.
    externalDocs:
      description: Observability guide
      url: https://docs.revoengine.com/operate/observability
  - name: Agent Memory
    description: Administrative access to durable Agent memory.
    externalDocs:
      description: Agent memory and workspaces guide
      url: https://docs.revoengine.com/ai/memory-and-workspaces
  - name: Agent Plugins
    description: Agent plugin definitions, synchronization, testing, and lifecycle.
    externalDocs:
      description: Agent plugins guide
      url: https://docs.revoengine.com/ai/plugins
  - name: Agents
    description: >-
      Agent definitions, runs, sessions, inboxes, memory, tools, workspaces, and
      lifecycle.
    externalDocs:
      description: Autonomous Agents guide
      url: https://docs.revoengine.com/ai/agents
  - name: Assistant
    description: >-
      Assistant threads, messages, responses, goals, reports, sharing,
      attachments, and control.
    externalDocs:
      description: Assistant guide
      url: https://docs.revoengine.com/ai/assistant
  - name: Automation
    description: >-
      Jobs, templates, schedules, events, webhooks, execution history, and
      lifecycle.
    externalDocs:
      description: Automation guide
      url: https://docs.revoengine.com/operate/automation
  - name: Chat
    description: Collaborative chat threads, messages, reactions, uploads, and attachments.
    externalDocs:
      description: Team Chat guide
      url: https://docs.revoengine.com/operate/chat
  - name: Component deployments
    description: >-
      Custom Node.js runtime deployment attempts, readiness, activation, and
      rollback.
    externalDocs:
      description: Custom Node.js guide
      url: https://docs.revoengine.com/build/custom-nodejs
  - name: Components
    description: Components, elements, versions, validation, activation, and lifecycle.
    externalDocs:
      description: Components guide
      url: https://docs.revoengine.com/build/components
  - name: Config
    description: Instance configuration, usage, logs, and cache administration.
    externalDocs:
      description: Instance settings guide
      url: https://docs.revoengine.com/platform/instance-settings
  - name: Database Cache
    description: Instance Database cache values and statistics.
    externalDocs:
      description: Database Cache guide
      url: https://docs.revoengine.com/operate/database-cache
  - name: Database Views
    description: Database Views, previews, refreshes, exports, and controlled data actions.
    externalDocs:
      description: Database Views guide
      url: https://docs.revoengine.com/operate/database-views
  - name: Databases
    description: Database definitions, data, audits, exports, cloning, and lifecycle.
    externalDocs:
      description: Databases guide
      url: https://docs.revoengine.com/operate/databases
  - name: Endpoints
    description: >-
      Endpoint definitions, activation, validation, generated OpenAPI, and
      statistics.
    externalDocs:
      description: Endpoints guide
      url: https://docs.revoengine.com/operate/endpoints
  - name: Files
    description: Compatibility file listing, preview, download, and deletion operations.
    externalDocs:
      description: Files compatibility guide
      url: https://docs.revoengine.com/operate/files
  - name: Groups
    description: Groups, membership, avatars, and lifecycle.
    externalDocs:
      description: Groups guide
      url: https://docs.revoengine.com/operate/groups
  - name: Me
    description: Current user profile, keys, avatar, and session information.
    externalDocs:
      description: Authentication guide
      url: https://docs.revoengine.com/developers/authentication
  - name: Preferences
    description: User and instance preference values.
    externalDocs:
      description: Platform UI guide
      url: https://docs.revoengine.com/platform/ui-tour
  - name: Role Groups
    description: Role groups, members, assigned roles, and lifecycle.
    externalDocs:
      description: Permissions guide
      url: https://docs.revoengine.com/operate/permissions
  - name: Roles
    description: Available platform roles and role details.
    externalDocs:
      description: Permissions guide
      url: https://docs.revoengine.com/operate/permissions
  - name: Search
    description: Cross-domain search over objects visible to the caller.
    externalDocs:
      description: Search and discovery guide
      url: https://docs.revoengine.com/platform/search
  - name: Secrets
    description: >-
      Secret definitions, revisions, activation, reveal, disable, and
      destruction.
    externalDocs:
      description: Secrets guide
      url: https://docs.revoengine.com/operate/secrets
  - name: Storage
    description: >-
      Storage workspaces, folders, objects, upload sessions, signed access, and
      lifecycle.
    externalDocs:
      description: Storage guide
      url: https://docs.revoengine.com/operate/storage
externalDocs:
  description: Documentation
  url: https://docs.revoengine.com
paths:
  /api/v1/config/instance/usage:
    get:
      tags:
        - Config
      summary: Retrieve instance usage analytics.
      description: |2-

            ROLES: INSTANCE_ADMIN
            USER: true
            SERVICE ACCOUNT: true

            Assistant analytics use the same selected UTC period across totals, model,
            account, and daily-series views. The lower bound is inclusive and the upper
            bound is exclusive. Omit both bounds for the current UTC month through now.
            
      operationId: ConfigController_current
      parameters:
        - name: from
          required: false
          in: query
          description: >-
            Inclusive lower UTC timestamp for assistant usage analytics.
            Defaults to the start of the current UTC month.
          schema:
            example: '2026-08-01T00:00:00.000Z'
            type: string
        - name: to
          required: false
          in: query
          description: >-
            Exclusive upper UTC timestamp for assistant usage analytics.
            Defaults to the current time.
          schema:
            example: '2026-09-01T00:00:00.000Z'
            type: string
      responses:
        '200':
          description: >-
            Instance usage counters and Assistant analytics for the normalized
            selected period.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstanceUsageResponseDto'
        '401':
          description: Not authorized.
      security:
        - bearer: []
components:
  schemas:
    InstanceUsageResponseDto:
      type: object
      properties:
        iam:
          $ref: '#/components/schemas/InstanceUsageIamDto'
        files:
          $ref: '#/components/schemas/InstanceUsageFilesDto'
        automation:
          $ref: '#/components/schemas/InstanceUsageAutomationDto'
        assistant:
          $ref: '#/components/schemas/InstanceAssistantUsageDto'
        databases:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        databaseSize:
          type: number
          example: 1048576
        databaseTableSize:
          type: number
          example: 524288
        materializedViewSize:
          type: number
          example: 262144
        databaseAuditSize:
          type: number
          example: 262144
        secrets:
          $ref: '#/components/schemas/InstanceUsageCountDto'
      required:
        - iam
        - files
        - automation
        - assistant
        - databases
        - databaseSize
        - databaseTableSize
        - materializedViewSize
        - databaseAuditSize
        - secrets
    InstanceUsageIamDto:
      type: object
      properties:
        accounts:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        platformAccounts:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        permissions:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        groups:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        apiKeys:
          $ref: '#/components/schemas/InstanceUsageCountDto'
      required:
        - accounts
        - platformAccounts
        - permissions
        - groups
        - apiKeys
    InstanceUsageFilesDto:
      type: object
      properties:
        totalTransfer:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        totalSize:
          $ref: '#/components/schemas/InstanceUsageCountDto'
      required:
        - totalTransfer
        - totalSize
    InstanceUsageAutomationDto:
      type: object
      properties:
        events:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        schedulers:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        jobTemplates:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        endpoints:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        components:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        eventsHistory:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        webhooks:
          $ref: '#/components/schemas/InstanceUsageCountDto'
        jobsProcessingTime:
          $ref: '#/components/schemas/InstanceUsageCountDto'
      required:
        - events
        - schedulers
        - jobTemplates
        - endpoints
        - components
        - eventsHistory
        - webhooks
        - jobsProcessingTime
    InstanceAssistantUsageDto:
      type: object
      properties:
        selectedPeriod:
          $ref: '#/components/schemas/InstanceUsageSelectedPeriodDto'
        tokenUsageCurrentBillingPeriod:
          $ref: '#/components/schemas/InstanceUsageTokenBreakdownDto'
        tokenUsagePreviousBillingPeriod:
          $ref: '#/components/schemas/InstanceUsageTokenBreakdownDto'
        tokenUsageTotal:
          $ref: '#/components/schemas/InstanceUsageTokenBreakdownDto'
        tokenUsageSelectedPeriod:
          $ref: '#/components/schemas/InstanceUsageTokenBreakdownDto'
        tokenUsageByModel:
          type: array
          items:
            $ref: '#/components/schemas/InstanceUsageTokenByModelDto'
        tokenUsageByAccount:
          type: array
          items:
            $ref: '#/components/schemas/InstanceUsageTokenByAccountDto'
        tokenUsageSeries:
          type: array
          items:
            $ref: '#/components/schemas/InstanceUsageTokenPointDto'
        tokenUsageAllTimeSeries:
          type: array
          items:
            $ref: '#/components/schemas/InstanceUsageTokenPointDto'
      required:
        - selectedPeriod
        - tokenUsageCurrentBillingPeriod
        - tokenUsagePreviousBillingPeriod
        - tokenUsageTotal
        - tokenUsageSelectedPeriod
        - tokenUsageByModel
        - tokenUsageByAccount
        - tokenUsageSeries
        - tokenUsageAllTimeSeries
    InstanceUsageCountDto:
      type: object
      properties:
        total:
          type: number
          example: 12
        enabled:
          type: number
          example: 10
        disabled:
          type: number
          example: 2
        serviceAccount:
          type: number
          example: 3
        notserviceAccount:
          type: number
          example: 9
        platformAccess:
          type: number
          example: 4
        notplatformAccess:
          type: number
          example: 8
      required:
        - total
    InstanceUsageSelectedPeriodDto:
      type: object
      properties:
        from:
          type: string
          format: date-time
          example: '2026-08-01T00:00:00.000Z'
        to:
          type: string
          format: date-time
          description: Exclusive upper bound.
          example: '2026-08-14T00:00:00.000Z'
      required:
        - from
        - to
    InstanceUsageTokenBreakdownDto:
      type: object
      properties:
        inputTokens:
          type: number
          example: 125000
        uncachedInputTokens:
          type: number
          example: 90000
        outputTokens:
          type: number
          example: 32000
        cachedInputTokens:
          type: number
          example: 35000
        reasoningTokens:
          type: number
          example: 8000
        totalTokens:
          type: number
          description: 'Billable token total: uncached input + 10% of cached input + output.'
          example: 125500
      required:
        - inputTokens
        - uncachedInputTokens
        - outputTokens
        - cachedInputTokens
        - reasoningTokens
        - totalTokens
    InstanceUsageTokenByModelDto:
      type: object
      properties:
        inputTokens:
          type: number
          example: 125000
        uncachedInputTokens:
          type: number
          example: 90000
        outputTokens:
          type: number
          example: 32000
        cachedInputTokens:
          type: number
          example: 35000
        reasoningTokens:
          type: number
          example: 8000
        totalTokens:
          type: number
          description: 'Billable token total: uncached input + 10% of cached input + output.'
          example: 125500
        model:
          type: string
          description: Execution model identifier used to group this usage.
      required:
        - inputTokens
        - uncachedInputTokens
        - outputTokens
        - cachedInputTokens
        - reasoningTokens
        - totalTokens
        - model
    InstanceUsageTokenByAccountDto:
      type: object
      properties:
        inputTokens:
          type: number
          example: 125000
        uncachedInputTokens:
          type: number
          example: 90000
        outputTokens:
          type: number
          example: 32000
        cachedInputTokens:
          type: number
          example: 35000
        reasoningTokens:
          type: number
          example: 8000
        totalTokens:
          type: number
          description: 'Billable token total: uncached input + 10% of cached input + output.'
          example: 125500
        userId:
          type: string
          format: uuid
        name:
          type: string
          example: Ada Lovelace
        mail:
          type: string
          nullable: true
          example: ada@example.com
      required:
        - inputTokens
        - uncachedInputTokens
        - outputTokens
        - cachedInputTokens
        - reasoningTokens
        - totalTokens
        - userId
        - name
    InstanceUsageTokenPointDto:
      type: object
      properties:
        inputTokens:
          type: number
          example: 125000
        uncachedInputTokens:
          type: number
          example: 90000
        outputTokens:
          type: number
          example: 32000
        cachedInputTokens:
          type: number
          example: 35000
        reasoningTokens:
          type: number
          example: 8000
        totalTokens:
          type: number
          description: 'Billable token total: uncached input + 10% of cached input + output.'
          example: 125500
        period:
          type: string
          description: >-
            UTC day for a selected-period series or UTC month for an all-time
            series.
          example: '2026-08-13'
      required:
        - inputTokens
        - uncachedInputTokens
        - outputTokens
        - cachedInputTokens
        - reasoningTokens
        - totalTokens
        - period
  securitySchemes:
    bearer:
      scheme: bearer
      bearerFormat: JWT
      description: Bearer JWT token or API Key (sk-*).
      type: http

````