Export Workflow Usage

API endpoint to export workflow usage data including cost, run counts, and monthly cap utilization

This endpoint exports workflow usage data including cost per workflow, run counts, and monthly cap utilization.

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.
Privacy: When user-level data is disabled, workflow_owner_id and workflow_owner_email are omitted, and owner-only private workflows are excluded.

Base URL

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

Data Included

The workflow export returns one row per non-template workflow that had runs or cost in 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
`workflow_id`	ID of the workflow
`workflow_name`	Name of the workflow
`status`	`ACTIVE`, `INACTIVE`, or `NOT_DEPLOYED`
`runs`	Number of workflow runs in the selected period
`total_cost_usd`	Cost in USD for the selected period
`monthly_limit_usd`	Current monthly USD cap for the workflow; `null` when no cap is set
`current_month_cost_usd`	Cost in USD for the current calendar month
`monthly_utilization_pct_current`	`current_month_cost_usd / monthly_limit_usd`; `null` when no cap is set
`workflow_owner_id`	ID of the workflow owner; excluded when user-level data is disabled
`workflow_owner_email`	Email of the workflow owner; excluded when user-level data is disabled

monthly_limit_usd, current_month_cost_usd, and monthly_utilization_pct_current use the workflow monthly USD cap and current calendar-month spend. They are not the extra-usage fields from the user export.

Additional Columns for BYOK Workspaces

Column	Description
`sum_input_tokens`	Total input tokens
`sum_cached_input_tokens`	Cache-read input tokens
`sum_cache_creation_tokens`	Cache-write input tokens
`sum_output_tokens`	Total output tokens

group_by is not supported for workflow exports.

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/workflows:
    post:
      tags:
        - Usage Export
      summary: Export workflow usage data
      description: >-
        Export cost, run counts, and monthly cap utilization for workflows in
        the workspace
      parameters: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UsageExportRequest'
      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:
    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
    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
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: API key as Bearer token. Format "Bearer YOUR_API_KEY"