Export Agent Usage

API endpoint to export agent usage data including message counts, active users, and trends

This endpoint exports agent usage data including message counts per agent, active user counts, and usage trends over time.

Before You Start

Prerequisites and rate limits: See the Usage Export API overview.
Browser requests: ajan intentionally blocks browser-origin requests to protect your API key. Use API keys server-side and store them securely. See API Key Best Practices.

Base URL

https://api.ajan.io/export/agents

The legacy path /export/assistants remains available and returns the same data.

Data Included

By default, the agent export returns one row per agent for the selected period.

Column	Description
`period_start`	Start date of the report
`period_end`	End date of the report
`org_id`	ID of the workspace
`assistant_id`	ID of the agent
`assistant_name`	Name of the agent
`model`	Model configured on the agent; empty when unset
`messages`	Number of user messages sent to the agent
`unique_users`	Number of users who messaged the agent
`active_users`	Number of active users from agent analytics
`conversations`	Number of conversations from agent analytics
`messages_per_user`	Average messages per active user
`assistant_description`	Agent description; excluded when user-level data is disabled
`assistant_url`	Link to the agent; excluded when user-level data is disabled
`assistant_owner_id`	ID of the agent owner; excluded when user-level data is disabled
`assistant_owner_email`	Email of the agent owner; excluded when user-level data is disabled

Additional Columns for BYOK Workspaces

Column	Description
`sum_prompt_tokens`	Total input tokens
`avg_prompt_tokens`	Average input tokens per request
`min_prompt_tokens`	Minimum input tokens per request
`max_prompt_tokens`	Maximum input tokens per request
`sum_completion_tokens`	Total output tokens
`avg_completion_tokens`	Average output tokens per request
`min_completion_tokens`	Minimum output tokens per request
`max_completion_tokens`	Maximum output tokens per request
`sum_cached_prompt_tokens`	Cache-read input tokens
`sum_cache_creation_tokens`	Cache-write input tokens
`sum_no_cache_tokens`	Input tokens that were not served from cache

Grouped Export

Use group_by=model to return one row per agent and model. In grouped rows, model is the model that produced the usage, not the model configured on the agent. Agent-level KPI fields are omitted in grouped mode.

OpenAPI

openapi: 3.0.0
info:
  title: ajan API
  version: 3.0.0
servers:
  - url: https://api.ajan.io
    description: Production
security:
  - bearerAuth: []
paths:
  /export/agents:
    post:
      tags:
        - Usage Export
      summary: Export agent usage data
      description: Export detailed usage data for all agents in the workspace
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageExportModelGroupByRequest'
            example:
              from:
                date: '2024-01-01T00:00:00.000Z'
                timezone: UTC
              to:
                date: '2024-01-31T23:59:59.999Z'
                timezone: UTC
      responses:
        '200':
          description: Export successful
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportResponse'
              example:
                success: true
                data:
                  filePath: >-
                    assistants-usage/workspace-id/assistants-usage-2024-01-01-2024-01-31-abc12345.csv
                  downloadUrl: https://storage.example.com/signed-url
                  dataType: assistants
                  recordCount: 1250
                  dateRange:
                    from: '2024-01-01T00:00:00.000Z'
                    to: '2024-01-31T23:59:59.999Z'
        '400':
          description: Bad Request - Export too large or invalid date range
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportError'
              example:
                message: >-
                  Export too large: more than 1,000,000 usage rows for the
                  selected date range. Try a shorter date range and combine the
                  CSV files.
                code: USAGE_EXPORT_TOO_LARGE
                details:
                  usageRows: 1500000
                  limit: 1000000
        '401':
          description: Unauthorized - Invalid or missing API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportError'
              example:
                message: The provided API key is invalid.
        '404':
          description: No data found for the selected period
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UsageExportError'
              example:
                message: No usage data found for the selected period
                code: NOT_FOUND
components:
  schemas:
    UsageExportModelGroupByRequest:
      allOf:
        - $ref: '#/components/schemas/UsageExportRequest'
        - type: object
          properties:
            group_by:
              type: string
              description: Optional aggregation dimension.
              enum:
                - model
    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
                - workflows
              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:
        message:
          type: string
          description: Detailed error message
          example: No usage data found for the selected period
        code:
          type: string
          description: Machine-readable error code
          example: NOT_FOUND
        details:
          type: object
          description: >-
            Additional error context. Oversized exports include the scanned row
            counts and the configured row limit.
      required:
        - 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"