# analytics_financial_details_retrieve

Financial Details Analytics API – paginated cost tables with flexible grouping.

This endpoint returns tabular cost metrics aggregated by the dimension
specified via the group_by query parameter.  One or more KPI columns
can be requested through the comma-separated metrics list while
typical filters (date range, provider, platform_key, user, etc.) narrow the
dataset.  Results are paginated with page / limit.

Required query parameters
- group_by – provider | llm_model | username | mentor | platform
- metrics – csv list of KPI names, e.g. total_cost, sessions

Shared optional filters
- start_date, end_date   – ISO yyyy-mm-dd (ignored when all_time=true)
- platform_key           – tenant isolation
- mentor_unique_id       – filter to one mentor
- username               – filter to a learner
- provider / llm_model   – filter to LLM provider / model
- all_time               – true → lifetime totals
- page (default 1), limit (default 50)

Examples
--------
1. Cost by provider for the last week

   GET /api/v2/analytics/financial/details?
       group_by=provider&
       metrics=total_cost&
       start_date=2025-01-01&
       end_date=2025-01-07&
       page=1&limit=10


2. Lifetime cost per user with extra KPIs
   
   GET /api/v2/analytics/financial/details?
       group_by=username&
       metrics=total_cost,sessions&
       all_time=true&page=1&limit=50
   
3. Cost by LLM model with tenant filter

   GET /api/v2/analytics/financial/details?
       group_by=llm_model&
       metrics=total_cost&
       platform_key=web-app&
       start_date=2025-01-01&end_date=2025-01-31

Response structure
-------------------
``
{
  "page": 1,
  "limit": 10,
  "total_pages": 1,
  "total_records": 3,
  "rows": [
    {"provider": "openai", "total_cost": "2.50000"},
    {"provider": "anthropic", "total_cost": "1.00000"},
    {"provider": "azure",    "total_cost": "0.50000"}
  ],
  "metrics": [
    {
      "name": "total_cost",
      "unit": "$",
      "description": "Cost for this entity in period"
    }
  ],
  "total_cost": "4.00000"   // optional grand-total when available
}
`

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

## Query parameters:

  - `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)

  - `group_by` (string, required)
    Dimension to group by

* provider - Group by provider
* llm_model - Group by LLM model
* username - Group by username
* mentor - Group by mentor
* platform - Group by platform
* action - Group by actions
    Enum: "provider", "llm_model", "username", "mentor", "platform", "action"

  - `limit` (integer)

  - `llm_model` (string)

  - `mentor_unique_id` (string)

  - `metrics` (string)
    Comma-separated list of metrics (e.g. total_cost,sessions, last_active)

  - `page` (integer)

  - `platform_key` (string)

  - `provider` (string)

  - `search` (string)

  - `start_date` (string)

  - `username` (string)

## Response 200 fields (application/json):

  - `page` (integer, required)

  - `limit` (integer, required)

  - `total_pages` (integer, required)

  - `total_records` (integer, required)

  - `rows` (any)

  - `total_cost` (string)

  - `metrics` (array)

  - `metrics.name` (string, required)

  - `metrics.unit` (string, required)

  - `metrics.description` (string, required)


## Response 400 fields

## Response 500 fields