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

# Model Requests

> Retrieve per-request model usage for your organization



## OpenAPI

````yaml /api-reference/openapi-org.yaml post /v2/organization/model-requests
openapi: 3.0.3
info:
  title: Firebender Organization API
  description: Organization usage analytics API
  version: 0.1.0
  contact:
    email: help@firebender.com
servers:
  - url: https://api.firebender.com
    description: Organization API
security:
  - apiKeyAuth: []
  - bearerAuth: []
paths:
  /v2/organization/model-requests:
    post:
      summary: Model Requests
      description: Retrieve per-request model usage for your organization
      operationId: getOrganizationModelRequests
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ModelRequestsRequest'
      responses:
        '200':
          description: Model request data retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ModelRequestsResponse'
        '400':
          description: Invalid request body, cursor, or date parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized - invalid or missing API key or authorization token
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden - authenticated user is not a member of an organization
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      security:
        - apiKeyAuth: []
        - bearerAuth: []
components:
  schemas:
    ModelRequestsRequest:
      type: object
      required:
        - startDate
        - endDate
      properties:
        startDate:
          type: integer
          format: int64
          description: >-
            Start of the time window as a Unix timestamp in milliseconds. Data
            is only available on or after 2025-12-31T00:00:00Z
          example: 1767222900000
        endDate:
          type: integer
          format: int64
          description: End of the time window as a Unix timestamp in milliseconds
          example: 1767226560000
        email:
          type: string
          format: email
          description: Optional email filter scoped to the organization
          example: user1@firebender.com
        cursor:
          type: string
          nullable: true
          description: Opaque cursor returned by a previous response for pagination
          example: >-
            eyJjcmVhdGVkQXRNcyI6MTc2NzIyNjUwMDAwMCwiaWQiOiIwZjhmYWQ1Yi1kOWNiLTQ2OWYtYTE2NS03MDg2NzcyODk1MGUifQ==
        limit:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
          description: Number of rows to return
          example: 100
    ModelRequestsResponse:
      type: object
      required:
        - data
        - nextCursor
      properties:
        data:
          type: array
          description: Array of model request records sorted oldest first
          items:
            $ref: '#/components/schemas/ModelRequestRecord'
        nextCursor:
          type: string
          nullable: true
          description: Cursor for the next page, or null when there are no more results
          example: null
    Error:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid API key
    ModelRequestRecord:
      type: object
      required:
        - requestId
        - timestamp
        - email
        - model
        - inputTokens
        - cacheReadTokens
        - outputTokens
        - cacheWriteTokens
        - totalTokens
        - costUsd
        - spendType
      properties:
        requestId:
          type: string
          format: uuid
          description: Unique request identifier
          example: 0f8fad5b-d9cb-469f-a165-70867728950e
        timestamp:
          type: string
          format: date-time
          description: Request timestamp in ISO 8601 format
          example: '2026-01-01T00:15:00Z'
        email:
          type: string
          format: email
          description: User email address
          example: user1@firebender.com
        model:
          type: string
          description: >-
            Model identifier used for the request. See
            [Models](https://docs.firebender.com/get-started/models) for valid
            model IDs
          example: gpt-5.4
        inputTokens:
          type: integer
          description: Input tokens billed for the request
          example: 120
        cacheReadTokens:
          type: integer
          description: Cache read tokens billed for the request
          example: 25
        outputTokens:
          type: integer
          description: Output tokens billed for the request
          example: 30
        cacheWriteTokens:
          type: integer
          description: Cache write tokens billed for the request
          example: 5
        totalTokens:
          type: integer
          description: Sum of input, cache read, output, and cache write tokens
          example: 180
        costUsd:
          type: number
          format: double
          description: Request cost in USD
          example: 1.2345
        spendType:
          type: string
          enum:
            - included
            - on-demand
            - byok
          description: >-
            Spending bucket for the request. `included` is plan-included usage,
            `on-demand` is metered overage usage, and `byok` is
            bring-your-own-key usage
          example: on-demand
        mode:
          type: string
          description: >-
            Agent mode when available. Built-in modes include write, plan, ask,
            and debug. This can also be another user-defined string for custom
            agents. See https://docs.firebender.com/api-reference/agents
          example: write
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: >-
        Organization API key. Create API Key
        [here](https://firebender.com/settings?tab=settings)
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Signed-in user authorization token for a user who belongs to the
        organization

````