openapi: 3.0.3
info:
  title: Eraser AI Requests Usage Metrics API
  description: The Eraser REST API provides programmatic access to diagram generation, file management, folder management, audit logs, and team usage metrics. Developers can generate diagrams from natural language prompts or Eraser DSL, create and manage files and diagrams on the canvas, and retrieve aggregated usage metrics. API access requires a team API token and is available on Starter, Business, and Enterprise paid plans with usage-based billing for API calls beyond plan credits.
  version: v1.0
  contact:
    name: Eraser Support
    url: https://www.eraser.io/
    email: hello@eraser.io
  termsOfService: https://www.eraser.io/
servers:
- url: https://app.eraser.io
  description: Eraser API Server
security:
- bearerAuth: []
tags:
- name: Usage Metrics
  description: Retrieve team usage and activity metrics
paths:
  /api/reports/usage:
    get:
      operationId: getUsageMetrics
      summary: Get team usage metrics
      description: Retrieves aggregated usage metrics for the team, including active members, file counts, and AI credit usage over a configurable date range.
      tags:
      - Usage Metrics
      externalDocs:
        description: API documentation
        url: https://docs.eraser.io/reference/get-usage-metrics
      parameters:
      - name: rangeDays
        in: query
        required: false
        description: Number of days to include in the report. Defaults to 30, min 1, max 365.
        schema:
          type: integer
          minimum: 1
          maximum: 365
          default: 30
      - name: endDate
        in: query
        required: false
        description: End date for the report range (YYYY-MM-DD format).
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Usage metrics retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageMetricsResponse'
        '400':
          description: Invalid request parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Missing or invalid bearer token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Unauthorized - token is valid but lacks permission
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: Service temporarily unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    UsageMemberMetrics:
      type: object
      properties:
        email:
          type: string
          description: Member email address
        displayName:
          type: string
          description: Member display name
        filesCreated:
          type: integer
          description: Number of files created in range
        filesViewed:
          type: integer
          description: Number of unique files viewed in range
        fileViews:
          type: integer
          description: Total file view count in range
        aiCreditsUsed:
          type: integer
          description: AI credits consumed in range
        lastActive:
          type: string
          format: date-time
          description: ISO 8601 timestamp of last activity
    Error:
      type: object
      properties:
        error:
          type: string
          description: Error message describing what went wrong
    UsageMetricsResponse:
      type: object
      required:
      - range
      - aggregate
      - members
      properties:
        range:
          type: object
          required:
          - start
          - end
          properties:
            start:
              type: string
              format: date
              description: Report range start date
            end:
              type: string
              format: date
              description: Report range end date
        aggregate:
          type: object
          properties:
            teamName:
              type: string
              description: Team name
            totalMembers:
              type: integer
              description: Total team members
            activeMembers:
              type: integer
              description: Members active in the period
            inactiveMembers:
              type: integer
              description: Members inactive in the period
            totalFiles:
              type: integer
              description: Total files in the team
            totalFilesCreated:
              type: integer
              description: Files created in the period
            totalFilesViewed:
              type: integer
              description: Unique files viewed in the period
            totalFileViews:
              type: integer
              description: Total file views in the period
            totalAiCreditsUsed:
              type: integer
              description: Total AI credits used in the period
        members:
          type: array
          items:
            $ref: '#/components/schemas/UsageMemberMetrics'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Team-specific API bearer token from Eraser settings
    auditApiKey:
      type: apiKey
      in: header
      name: Authorization
      description: Audit-specific API key for accessing audit log endpoints
externalDocs:
  description: Eraser API Documentation
  url: https://docs.eraser.io/docs/eraser-api