Agent kullanımını dışa aktar

Mesaj sayıları, aktif kullanıcılar ve trendler dahil agent kullanım verilerini dışa aktaran API endpoint'i

Bu endpoint; agent başına mesaj sayıları, aktif kullanıcı sayıları ve zaman içindeki kullanım trendleri dahil agent kullanım verilerini dışa aktarır.

Başlamadan önce

Önkoşullar ve rate limit'ler: Usage Export API overview sayfasına bakın.
Tarayıcı istekleri: ajan, API anahtarınızı korumak için tarayıcı kaynaklı istekleri bilinçli olarak engeller. API anahtarlarını sunucu tarafında kullanın ve güvenli saklayın. Bkz. API Key Best Practices.

Base URL

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

Dedicated deployments Tüm isteklerde api.ajan.com'u /api/public ile değiştirin.

Eski /export/assistants yolu hâlâ kullanılabilir ve aynı veriyi döndürür.

Dahil edilen veriler

Varsayılan olarak agent dışa aktarımı, seçilen dönem için agent başına bir satır döndürür.

Column	Description
`period_start`	Raporun başlangıç tarihi
`period_end`	Raporun bitiş tarihi
`org_id`	Workspace kimliği
`assistant_id`	Agent kimliği
`assistant_name`	Agent adı
`model`	Agent üzerinde yapılandırılan model; ayarlanmamışsa boş
`messages`	Agent'a gönderilen kullanıcı mesajı sayısı
`unique_users`	Agent'a mesaj gönderen kullanıcı sayısı
`active_users`	Agent analitiginden aktif kullanıcı sayısı
`conversations`	Agent analitiginden konuşma sayısı
`messages_per_user`	Aktif kullanıcı başına ortalama mesaj
`assistant_description`	Agent açıklaması; kullanıcı düzeyinde veri kapalıysa hariç tutulur
`assistant_url`	Agent bağlantısı; kullanıcı düzeyinde veri kapalıysa hariç tutulur
`assistant_owner_id`	Agent sahibi kimliği; kullanıcı düzeyinde veri kapalıysa hariç tutulur
`assistant_owner_email`	Agent sahibi e-postası; kullanıcı düzeyinde veri kapalıysa hariç tutulur

BYOK workspace'leri için ek sütunlar

Column	Description
`sum_prompt_tokens`	Toplam girdi token'ı
`avg_prompt_tokens`	İstek başına ortalama girdi token'ı
`min_prompt_tokens`	İstek başına minimum girdi token'ı
`max_prompt_tokens`	İstek başına maksimum girdi token'ı
`sum_completion_tokens`	Toplam çıktı token'ı
`avg_completion_tokens`	İstek başına ortalama çıktı token'ı
`min_completion_tokens`	İstek başına minimum çıktı token'ı
`max_completion_tokens`	İstek başına maksimum çıktı token'ı
`sum_cached_prompt_tokens`	Önbellekten okunan girdi token'ları
`sum_cache_creation_tokens`	Önbelleğe yazılan girdi token'ları
`sum_no_cache_tokens`	Önbellekten sunulmayan girdi token'ları

BYOK workspace'leri kendi model anahtarlarını sağladığı için ajan, token tüketim verilerini doğrudan sunabilir. Modellerinizi doğrudan ajan üzerinden aldığınızda bu mümkün değildir.

Gruplanmış dışa aktarım

Agent ve model başına bir satır için group_by=model kullanın. Gruplanmış satırlarda model, agent üzerinde yapılandırılan model değil, kullanımı üreten modeldir. Agent düzeyindeki KPI alanları gruplanmış modda atlanır.

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"