# analytics_financial_invoice_retrieve

Flexible Invoice Report API – Billing summary with username and platform filtering.

This endpoint generates invoice reports with flexible filtering options:
- Platform admins can view their platform's data and filter by username within their platform
- Super admins can view any combination of username/platform or global summaries

Key Features:
- Flexible filtering by username and/or platform_key
- Essential metrics: total cost, sessions, usage period
- Provider breakdown (OpenAI, Anthropic, etc.)
- Top mentors/actions by cost
- Clean, invoice-ready format

Query Parameters:
- username: Filter by specific username (optional)
- platform_key: Filter by platform (optional, but required for platform admins)
- start_date, end_date: billing period (defaults to last 30 days)
- include_breakdown: show provider/mentor details (default: true)

Permission Logic:
- Platform admins: Must include platform_key matching their permission scope
- Super admins: Can use any combination of filters or none (global summary)

Examples:

# Platform admin viewing their platform
GET /api/analytics/financial/invoice?platform_key=web-app

# Platform admin viewing specific user in their platform
GET /api/analytics/financial/invoice?platform_key=web-app&username=john.doe

# Super admin viewing specific user across all platforms
GET /api/analytics/financial/invoice?username=john.doe

# Super admin viewing global summary
GET /api/analytics/financial/invoice


Response Structure:
json
{
  "entity": {
    "type": "user|platform|global",
    "username": "john.doe",
    "platform_key": "web-app",
    "platform_name": "Web Application",
    "display_name": "John Doe on Web Application"
  },
  "billing_period": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "days": 31
  },
  "summary": {
    "total_cost": 245.750,
    "total_sessions": 1250,
    "active_users": 85,
    "cost_per_session": 0.196
  },
  "breakdown": {
    "by_provider": [...],
    "by_mentor": [...],
    "by_action": [...]
  }
}

Endpoint: GET /api/analytics/financial/invoice/
Version: 4.84.1-ai-plus
Security: PlatformApiKeyAuthentication

## Query parameters:

  - `end_date` (string)
    End date for billing period (defaults to today)

  - `include_breakdown` (boolean)
    Whether to include provider and mentor breakdown

  - `platform_key` (string)
    Platform key to filter by (optional, required for platform admins)

  - `start_date` (string)
    Start date for billing period (defaults to 30 days ago)

  - `username` (string)
    Username to generate invoice for (optional)

## Response 200 fields (application/json):

  - `entity` (object, required)
    Entity information for the invoice.

  - `entity.type` (string)
    * user - user
* platform - platform
* global - global
    Enum: "user", "platform", "global"

  - `entity.username` (string)

  - `entity.platform_key` (string)

  - `entity.platform_name` (string)

  - `entity.display_name` (string, required)

  - `billing_period` (object, required)
    Billing period information.

  - `billing_period.start_date` (string, required)

  - `billing_period.end_date` (string, required)

  - `billing_period.days` (integer, required)

  - `summary` (object, required)
    Summary metrics for the invoice.

  - `summary.total_cost` (string, required)

  - `summary.total_sessions` (integer, required)

  - `summary.active_users` (integer, required)

  - `summary.cost_per_session` (string, required)

  - `breakdown` (object)
    Detailed breakdown of costs.

  - `breakdown.by_provider` (array)

  - `breakdown.by_provider.provider` (string, required)

  - `breakdown.by_provider.cost` (string, required)

  - `breakdown.by_provider.percentage` (string, required)

  - `breakdown.by_mentor` (array)

  - `breakdown.by_mentor.mentor` (string, required)

  - `breakdown.by_mentor.sessions` (integer, required)

  - `breakdown.by_mentor.mentor_name` (string)

  - `breakdown.by_action` (array)

  - `breakdown.by_action.action` (string, required)

  - `breakdown.by_action.trace_count` (integer, required)

  - `breakdown.by_action.unique_users` (integer)


## Response 400 fields

## Response 403 fields

## Response 404 fields

## Response 500 fields