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

# Benchmark the monthly cost per active user of a group

> GoModel API reference for GET /admin/usage/benchmark: Benchmark the monthly cost per active user of a group.



## OpenAPI

````yaml /openapi.json get /admin/usage/benchmark
openapi: 3.0.0
info:
  description: >-
    AI gateway routing requests to multiple LLM providers (OpenAI, Anthropic,
    Gemini, Groq, Fireworks AI, Meta, OpenRouter, Kilo AI, DeepSeek, Z.ai, xAI,
    MiniMax, Xiaomi MiMo, Mistral AI, OpenCode Go, Oracle, Ollama, Bailian).
    Drop-in OpenAI-compatible API.
  title: GoModel API
  contact: {}
  version: '1.0'
servers:
  - url: '{base_url}'
    description: Edit the base URL to point at your GoModel deployment.
    variables:
      base_url:
        default: http://localhost:8080
        description: Your GoModel deployment URL
security: []
paths:
  /admin/usage/benchmark:
    get:
      tags:
        - admin
      summary: Benchmark the monthly cost per active user of a group
      description: >-
        Treats each direct child of parent as one user, summing its whole
        subtree, and returns per calendar month the number of active users (at
        least one request in the month, response-cache hits included), their
        total cost and the mean, median (p50), p90 and maximum cost per active
        user. Percentiles interpolate linearly between closest ranks. A user's
        cost is the one the invoice export reports for it; unpriced_users counts
        users whose cost is wholly unknown (counted at 0) and
        partly_priced_users those counted at a known part of it. Every user is
        counted; nothing is folded into an "other" bucket. Usage recorded on
        parent itself is reported as unattributed_cost. Months are read in the
        time zone of the X-GoModel-Timezone header (UTC without it); the current
        month is flagged partial and has no change percentages. A range covers
        at most 12 months; start_date, end_date and days, which the other usage
        endpoints take, are ignored. The response holds no user paths unless
        top_users asks for the highest-cost users of each month.
      parameters:
        - description: IANA time zone months are read in, e.g. Europe/Warsaw (default UTC)
          name: X-GoModel-Timezone
          in: header
          schema:
            type: string
        - description: >-
            Group whose direct children are the users, e.g. /eng (default: the
            credential's scope root, or /)
          name: parent
          in: query
          schema:
            type: string
        - description: >-
            Number of months ending at end_month, 1-12 (default 7: six complete
            months plus the current one); ignored with start_month
          name: months
          in: query
          schema:
            type: integer
        - description: 'First month (YYYY-MM, default: months before end_month)'
          name: start_month
          in: query
          schema:
            type: string
        - description: 'Last month (YYYY-MM, default and latest: the current month)'
          name: end_month
          in: query
          schema:
            type: string
        - description: >-
            provider (default) or billed; billed requires
            pricing.markups_enabled
          name: cost_basis
          in: query
          schema:
            type: string
        - description: >-
            List each month's N highest-cost users (0-50, default 0: aggregates
            only)
          name: top_users
          in: query
          schema:
            type: integer
        - description: Filter by exact model names; repeat or comma-separate for several
          name: model
          in: query
          explode: true
          schema:
            type: array
            items:
              type: string
        - description: >-
            Filter by provider names or types; repeat or comma-separate for
            several
          name: provider
          in: query
          explode: true
          schema:
            type: array
            items:
              type: string
        - description: Filter by request labels (exact match); repeat for several
          name: label
          in: query
          explode: true
          schema:
            type: array
            items:
              type: string
        - description: >-
            Filter by exact request endpoints, e.g.
            /v1/chat/completions,/v1/messages; repeat or comma-separate for
            several
          name: endpoint
          in: query
          explode: true
          schema:
            type: array
            items:
              type: string
        - description: >-
            Filter by comma-separated operations, e.g.
            chat_completions,embeddings
          name: operation
          in: query
          schema:
            type: string
        - description: Filter by exact detected session ID
          name: session_id
          in: query
          schema:
            type: string
        - description: Filter by managed auth key IDs; repeat or comma-separate for several
          name: auth_key_id
          in: query
          explode: true
          schema:
            type: array
            items:
              type: string
        - description: Filter by tracked user path subtrees; repeat for several
          name: user_path
          in: query
          explode: true
          schema:
            type: array
            items:
              type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/usage.Benchmark'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/core.GatewayError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/core.GatewayError'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/core.GatewayError'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/core.GatewayError'
      security:
        - BearerAuth: []
components:
  schemas:
    usage.Benchmark:
      type: object
      properties:
        cost_basis:
          type: string
          enum:
            - provider
            - billed
        currency:
          type: string
        months:
          type: array
          items:
            $ref: '#/components/schemas/usage.BenchmarkMonth'
        parent:
          type: string
        time_zone:
          type: string
    core.GatewayError:
      type: object
      properties:
        code:
          type: string
          nullable: true
        message:
          type: string
        param:
          type: string
          nullable: true
        provider:
          type: string
        status_code:
          type: integer
        type:
          $ref: '#/components/schemas/core.ErrorType'
    usage.BenchmarkMonth:
      type: object
      properties:
        active_users:
          type: integer
        max:
          type: number
          nullable: true
        mean:
          type: number
          nullable: true
        mean_change_percent:
          description: >-
            MeanChangePercent and P50ChangePercent compare with the previous
            month;

            nil for the first month, the partial current month, a month without

            active users, or a previous month whose value is not positive.
          type: number
          nullable: true
        month:
          type: string
        p50:
          type: number
          nullable: true
        p50_change_percent:
          type: number
          nullable: true
        p90:
          type: number
          nullable: true
        partial:
          type: boolean
        partly_priced_users:
          type: integer
        top_users:
          description: TopUsers is set only when requested.
          type: array
          items:
            $ref: '#/components/schemas/usage.BenchmarkUser'
        total_cost:
          type: number
        unattributed_cost:
          description: >-
            UnattributedCost is usage recorded on the parent path itself, which
            no

            user carries; it is not part of TotalCost.
          type: number
        unpriced_users:
          type: integer
    core.ErrorType:
      type: string
      enum:
        - provider_error
        - rate_limit_error
        - invalid_request_error
        - authentication_error
        - not_found_error
        - permission_error
        - internal_error
      x-enum-varnames:
        - ErrorTypeProvider
        - ErrorTypeRateLimit
        - ErrorTypeInvalidRequest
        - ErrorTypeAuthentication
        - ErrorTypeNotFound
        - ErrorTypePermission
        - ErrorTypeInternal
    usage.BenchmarkUser:
      type: object
      properties:
        cost:
          type: number
        requests:
          type: integer
        user:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.