Introduction to Usage Export

Use the Usage Export API to export workspace usage data as CSV or JSON.

The Usage Export API lets workspace administrators export usage data for users, agents, API keys, projects, models, and workflows. Use it when you want to automate reporting or pull data into an external analytics system.

Prerequisites

To use the Usage Export API, you need:

• Workspace Admin Permission: Only workspace administrators can create API keys with usage export permissions and export data via the web interface.
• API Key with USAGE\_EXPORT\_API Scope: Special permission for accessing export functions

Programmatic Export

Available Endpoints

The Usage Export API provides access to various data types:

POST /export/users
POST /export/agents
POST /export/api-keys
POST /export/projects
POST /export/models
POST /export/workflows

Each endpoint also supports explicit output format routes:

POST /export/{dataType}/csv
POST /export/{dataType}/json

Authentication

All API requests require Bearer token authentication:

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

Request Format

Time specification and time zone handling:\ The API uses the exact time included in the date parameter you provide & treats them as your local times, specified in the timezone parameter. If you include a "Z" at the end of your date (which stands for UTC/Zulu time), it automatically removes it to prevent the timezone from being applied twice.

{
  "from": {
    "date": "2024-01-01T00:00:00.000",
    "timezone": "Europe/Berlin"
  },
  "to": {
    "date": "2024-01-31T23:59:59.999", 
    "timezone": "UTC"
  },
  "group_by": "model"
}

group_by is optional. Supported values depend on the export type:

Requests with an unsupported group_by value return a 400 Bad Request.

Response Format

CSV Response

CSV endpoints return a file path and download URL:

{
  "success": true,
  "data": {
    "filePath": "agents-usage/workspace-id/agents-usage-2024-01-01-2024-01-31-abc12345.csv",
    "downloadUrl": "https://storage.example.com/signed-url",
    "dataType": "agents",
    "recordCount": 1250,
    "dateRange": {
      "from": "2024-01-01T00:00:00.000+01:00",
      "to": "2024-01-31T23:59:59.999"
    }
  }
}

JSON Response

JSON endpoints return rows directly:

{
  "success": true,
  "data": [
    {
      "period_start": "2024-01-01",
      "period_end": "2024-01-31",
      "org_id": "workspace-id"
    }
  ],
  "metadata": {
    "dataType": "users",
    "recordCount": 1,
    "dateRange": {
      "from": "2024-01-01T00:00:00.000Z",
      "to": "2024-01-31T23:59:59.999Z"
    }
  }
}

Error Response

{
  "message": "No usage data found for the selected period",
  "code": "NOT_FOUND"
}

Example Requests

Export Agent Usage

curl -X POST "https://api.ajan.io/export/agents" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "date": "2024-01-01T00:00:00.000",
      "timezone": "UTC"
    },
    "to": {
      "date": "2024-01-31T23:59:59.999",
      "timezone": "UTC"
    }
  }'

Export User Usage

curl -X POST "https://api.ajan.io/export/users" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "from": {
      "date": "2024-01-01T00:00:00.000",
      "timezone": "UTC"
    },
    "to": {
      "date": "2024-01-31T23:59:59.999",
      "timezone": "UTC"
    }
  }'

Export Limits

Each Usage Export API request can scan up to 1,000,000 usage rows. This limit applies to the default, CSV, and JSON endpoints.

Requests that exceed the limit return 400 Bad Request with the code USAGE_EXPORT_TOO_LARGE. The error message names the row limit, and details contains it as limit. Choose a shorter date range and combine the results.

Rate Limits

The Usage Export API is subject to a request rate limit, enforced per workspace and API key. The token limit that applies to completion endpoints does not apply here.

• Requests per Minute: 500 Requests/Min

Endpoint Details

• Export User Usage
• Export Agent Usage
• Export API Key Usage
• Export Project Usage
• Export Model Usage
• Export Workflow Usage

Troubleshooting

Common Errors

400 Bad Request - Unsupported group_by

{
  "message": "group_by=deployment is not supported for users exports",
  "code": "BAD_REQUEST"
}

Solution: Use a group_by value supported by the export type, or omit the field.

400 Bad Request: Export too large

{
  "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
  }
}

Solution: Choose a shorter date range and combine the results.

401 Unauthorized

{
  "message": "The provided API key is invalid."
}

Solution: Check that your API key is correct and has the USAGE\_EXPORT\_API permission.

404 No Data Found

{
  "message": "No usage data found for the selected period",
  "code": "NOT_FOUND"
}

Solution: Check the selected time period - there may have been no activity during this period.

Security and Privacy

Privacy Settings

Depending on workspace configuration, certain data may be excluded:

• User-identifying Data: May be excluded due to privacy settings
• Leaderboards: Must be enabled in the workspace to get complete user data

Best Practices

1. Secure API Key Storage: Use environment variables or secure key management
2. Regular Rotation: Renew API keys regularly
3. Minimal Permissions: Only grant necessary scopes
4. Monitoring: Monitor the usage of your API keys

Compliance

The Usage Export API helps with compliance requirements:

• Audit Trails: Complete tracking of API usage
• Data Export: Support for GDPR data access rights
• Transparency: Clear insights into workspace usage

Support

For questions about the Usage Export API, contact our support team or consult the complete API documentation.