# analytics_financial_retrieve

Financial Analytics API - Get comprehensive cost metrics with comparison analysis.

This endpoint provides period-based cost analysis (not cumulative) with support for:
- Multiple time granularities and metrics
- Cross-dimensional filtering
- Percentage change vs comparison periods
- Forward-filled time series

Examples:

Basic Weekly Costs:

GET /api/analytics/financial/?metric=weekly_costs&comparison_days=10


Platform & Mentor Filtered:

# Get total costs for a specific platform and mentor
GET /api/analytics/financial/?metric=total_costs&platform_key=web-app&mentor_unique_id=mentor-123&comparison_days=14


Monthly Costs by Provider:

GET /api/analytics/financial/?metric=monthly_costs&provider=openai&granularity=month&comparison_days=30


Daily Costs for Specific User:

GET /api/analytics/financial/?metric=total_costs&username=user-456&granularity=day&start_date=2025-01-15&end_date=2025-01-21&comparison_days=7



Response Structure:
json
{
    "metric": "weekly_costs",
    "value": 12.47,
    "percentage_change": 8.5,
    "overtime": [
        {"date": "2025-01-06", "value": 2.89},
        {"date": "2025-01-13", "value": 3.12}
    ],
    "period_info": {
        "start_date": "2025-01-01",
        "end_date": "2025-01-31",
        "period_days": 31
    },
    "comparison_info": {
        "previous_period_value": 11.50,
        ...
    }
}

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

## Query parameters:

  - `comparison_days` (integer)
    Number of days for comparison period to calculate percentage change (e.g., 10 for 10-day comparison)

  - `date_filter` (string)
    * today - Today only
* 7d - Last 7 days
* 30d - Last 30 days
* 90d - Last 90 days
* all_time - All time
* custom - Custom date range
    Enum: "today", "7d", "30d", "90d", "all_time", "custom"

  - `end_date` (string)

  - `fill_method` (string)
    Method for filling missing time periods in overtime data

* zero - Fill missing periods with zero
* previous - Fill missing periods with previous value
    Enum: "zero", "previous"

  - `granularity` (string)
    Time granularity for overtime series data

* day - Daily data points
* week - Weekly data points
* month - Monthly data points
    Enum: "day", "week", "month"

  - `llm_model` (string)
    Filter by specific LLM model (e.g., gpt-4o, claude-3-5-sonnet)

  - `mentor_unique_id` (string)

  - `metric` (string, required)
    Type of financial metric to retrieve

* total_costs - Total costs for selected timeframe
* weekly_costs - Costs for current/selected week
* monthly_costs - Costs for current/selected month
    Enum: "total_costs", "weekly_costs", "monthly_costs"

  - `platform_key` (string)

  - `provider` (string)
    Filter by AI provider

* openai - OpenAI
* anthropic - Anthropic
* azure - Azure
* google - Google
* meta - Meta
* other - Other
    Enum: "openai", "anthropic", "azure", "google", "meta", "other"

  - `show_overtime` (boolean)
    Whether to include overtime series data in response

  - `start_date` (string)

  - `username` (string)
    Filter by specific username - returns costs for this user only

## Response 200 fields (application/json):

  - `metric` (string, required)
    The metric type that was requested

  - `filters` (object, required)
    Applied filters for this query

  - `filters.start_date` (string)

  - `filters.end_date` (string)

  - `filters.granularity` (string, required)

  - `filters.comparison_days` (integer)

  - `filters.platform_key` (string)

  - `filters.mentor_unique_id` (string)

  - `filters.username` (string)

  - `filters.provider` (string)

  - `filters.llm_model` (string)

  - `filters.all_time` (boolean)

  - `value` (string, required)
    Primary metric value (cost in USD)

  - `percentage_change` (number,null, required)
    Percentage change vs comparison period (null if no comparison)

  - `overtime` (array, required)
    Time series data for overtime visualization

  - `overtime.date` (string, required)
    Date in YYYY-MM-DD format

  - `overtime.value` (string, required)
    Cost value for this time period

  - `period_info` (object, required)
    Information about the analysis period

  - `period_info.start_date` (string)
    Start date of analysis period

  - `period_info.end_date` (string)
    End date of analysis period

  - `period_info.period_days` (integer)
    Number of days in period

  - `period_info.range_type` (string)
    Type of date range (custom, default, all_time, etc.)

  - `comparison_info` (object, required)
    Information about comparison period (empty if no comparison)

  - `comparison_info.previous_period_count` (integer)
    Number of days in comparison period

  - `comparison_info.previous_period_value` (string)
    Cost value for comparison period

  - `comparison_info.comparison_start` (string)
    Start date of comparison period

  - `comparison_info.comparison_end` (string)
    End date of comparison period

  - `comparison_info.comparison_days` (integer)
    Number of comparison days

  - `comparison_info.recent_period_value` (string)
    Cost value for current period


## Response 400 fields

## Response 403 fields

## Response 500 fields