Export Model Usage

API endpoint to export AI model usage data including request counts and BYOK token consumption

Using a dedicated deployment?

Replace api.odeus.ai with <your-deployment>/api/public in all requests.

For details on prerequisites and rate limits, please refer to the main Usage Export API documentation.

Odeus intentionally blocks browser-origin requests to protect your API key and ensure your applications remain secure. For more information, please see our guide on API Key Best Practices.

This endpoint exports AI model usage data, including request counts per model.

Data Included

By default, the model export returns one row per normalized model name, provider, and BYOK state.

Column	Description
period_start	Start date of the report
period_end	End date of the report
org_id	ID of the workspace
name	Normalized model name
provider	Model provider
bring_your_keys	Whether usage came from a BYOK model
requests	Number of requests

Additional Columns for BYOK Workspaces

Column	Description
sum_prompt_tokens	Total input tokens
sum_completion_tokens	Total output tokens
sum_cached_prompt_tokens	Cache-read input tokens
sum_cache_creation_tokens	Cache-write input tokens
no_cache_tokens	Input tokens that were not served from cache
total_cost_usd	Estimated provider cost in USD

Because BYOK workspaces supply their own model keys, Odeus can provide you with an export of your token consumption data.

Grouped Export

Use group_by=source to return one row per model and source, such as WEB or MOBILE.

BYOK workspaces can also use group_by=deployment to return one row per model and deployment.

Usage Analysis

With this export you can:

• Calculate costs using your provider's pricing
• Identify which models receive the most requests
• Track usage trends over time
• Optimize model selection for different use cases

OpenAPI

openapi: 3.0.0
info:
  title: Odeus API
  version: 3.0.0
servers:
  - url: https://api.odeus.ai
security:
  - bearerAuth: []
paths:
  /export/models:
    post:
      tags:
        - Usage Export
      summary: Export model usage data
      description: Export detailed usage data for all AI models used in the workspace
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageExportModelsRequest'
      responses:
        '200':
          description: Export successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportError'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportError'
        '404':
          description: No data found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportError'
components:
  schemas:
    UsageExportModelsRequest:
      allOf:
        - $ref: '#/components/schemas/UsageExportRequest'
        - type: object
          properties:
            group_by:
              type: string
              description: >-
                Optional aggregation dimension. `deployment` is only available
                for BYOK workspaces.
              enum:
                - source
                - deployment
    UsageExportResponse:
      type: object
      description: Successful response from usage export endpoints
      properties:
        success:
          type: boolean
          description: Indicates if the export was successful
          example: true
        data:
          type: object
          description: Export data information
          properties:
            filePath:
              type: string
              description: Path to the generated export file
              example: >-
                agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv
            downloadUrl:
              type: string
              format: uri
              description: Signed URL to download the export file
              example: https://storage.example.com/signed-url
            dataType:
              type: string
              description: Type of data exported
              enum:
                - assistants
                - agents
                - api_keys
                - users
                - projects
                - models
              example: assistants
            recordCount:
              type: integer
              description: Number of records in the export
              example: 1250
            dateRange:
              type: object
              description: Actual date range of the exported data
              properties:
                from:
                  type: string
                  format: date-time
                  description: Start date of the export
                  example: '2024-01-01T00:00:00.000Z'
                to:
                  type: string
                  format: date-time
                  description: End date of the export
                  example: '2024-01-31T23:59:59.999Z'
              required:
                - from
                - to
          required:
            - filePath
            - downloadUrl
            - dataType
            - recordCount
            - dateRange
      required:
        - success
        - data
    UsageExportError:
      type: object
      description: Error response from usage export endpoints
      properties:
        error:
          type: string
          description: Error type
          example: No data found
        message:
          type: string
          description: Detailed error message
          example: No usage data found for the selected period
      required:
        - error
        - message
    UsageExportRequest:
      type: object
      description: Request body for usage export endpoints
      properties:
        from:
          type: object
          description: Start date and timezone for the export
          properties:
            date:
              type: string
              format: date-time
              description: Start date in ISO 8601 format
              example: '2024-01-01T00:00:00.000Z'
            timezone:
              type: string
              description: Timezone for the date range
              example: UTC
          required:
            - date
            - timezone
        to:
          type: object
          description: End date and timezone for the export
          properties:
            date:
              type: string
              format: date-time
              description: End date in ISO 8601 format
              example: '2024-01-31T23:59:59.999Z'
            timezone:
              type: string
              description: Timezone for the date range
              example: UTC
          required:
            - date
            - timezone
      required:
        - from
        - to
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"