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, and models. Use it when you want to automate reporting or pull data into an external analytics system.

You can also generate these exports in the Odeus UI. See Usage Exports.

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

Important Security Notice: Users with access to an API key with USAGE_EXPORT_API scope can export workspace usage data for all areas, even if they normally don't have access to view this data. Only grant this permission to trusted users.

Programmatic Export

Available Endpoints

The Usage Export API provides access to various data types:

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

The agents and assistants dataTypes return the same data — agents is an alias. Both paths work identically.

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:

Export	Supported group_by values
Users	model
Agents / Assistants	model
API keys	model
Models	source; deployment for BYOK workspaces only
Projects	Not supported

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": "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.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 Assistant Usage

curl -X POST "https://api.odeus.ai/export/assistants" \
  -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.odeus.ai/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"
    }
  }'

Rate Limits

The Usage Export API is subject to the same rate limits as other API endpoints:

• Tokens per Minute: 60,000 Tokens/Min
• Requests per Minute: 500 Requests/Min

Endpoint Details

• Export User Usage
• Export Agent Usage
• Export API Key Usage
• Export Project Usage
• Export Model 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.

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.

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.