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

# Query usage

> Query model usage with optional filtering by agent, model, request type, and date range. Supports grouping by agent, model, day, or request type. Users see own usage only (via owner column); admins see all.




## OpenAPI

````yaml /openapi.yaml get /usage
openapi: 3.0.3
info:
  title: Hill90 API
  description: Hill90 platform API — agent management and lifecycle operations.
  version: 0.1.0
servers:
  - url: /
    description: Relative (behind Traefik reverse proxy)
security: []
paths:
  /usage:
    get:
      summary: Query usage
      description: >
        Query model usage with optional filtering by agent, model, request type,
        and date range. Supports grouping by agent, model, day, or request type.
        Users see own usage only (via owner column); admins see all.
      parameters:
        - name: agent_id
          in: query
          schema:
            type: string
          description: Filter by agent ID
        - name: model_name
          in: query
          schema:
            type: string
          description: Filter by model name
        - name: request_type
          in: query
          schema:
            type: string
            enum:
              - chat.completion
              - embedding
          description: Filter by request type
        - name: from
          in: query
          schema:
            type: string
            format: date
          description: Start date (defaults to today)
        - name: to
          in: query
          schema:
            type: string
            format: date
          description: End date (inclusive)
        - name: group_by
          in: query
          schema:
            type: string
            enum:
              - agent
              - model
              - day
              - request_type
          description: Group results by dimension
      responses:
        '200':
          description: Usage data
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/UsageSummary'
                  - type: object
                    properties:
                      data:
                        type: array
                        items:
                          $ref: '#/components/schemas/UsageSummary'
                      group_by:
                        type: string
        '401':
          description: Not authenticated
        '403':
          description: Requires user role
      security:
        - bearerAuth: []
components:
  schemas:
    UsageSummary:
      type: object
      properties:
        total_requests:
          type: integer
        successful_requests:
          type: integer
        total_input_tokens:
          type: integer
        total_output_tokens:
          type: integer
        total_tokens:
          type: integer
        total_cost_usd:
          type: number
          format: double
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````