Skip to content
API Reference/
/
analytics_financial_detai...

ibl-data-manager (4.84.1-ai-plus)

API for iblai

Download OpenAPI description
ibl.json
ibl.yaml
Languages
Servers
Mock server
https://docs.ibl.ai/_mock/apis/ibl/
https://base.manager.iblai.app/

ai-account

Operations

ai-analytics

Operations

ai-bot

Operations

ai-finetuning

Operations

ai-index

Operations

ai-marketing

Operations

ai-media

Operations

ai-mentor

Operations

ai-prompt

Operations

analytics

Operations

analytics_financial_retrieve

Request

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:

{
    "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,
        ...
    }
}
Security
PlatformApiKeyAuthentication
Query
comparison_daysinteger>= 1

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

date_filterstringnon-empty
  • today - Today only
  • 7d - Last 7 days
  • 30d - Last 30 days
  • 90d - Last 90 days
  • all_time - All time
  • custom - Custom date range
Default "today"
Enum"today""7d""30d""90d""all_time""custom"
end_datestring(date)
fill_methodstringnon-empty

Method for filling missing time periods in overtime data

  • zero - Fill missing periods with zero
  • previous - Fill missing periods with previous value
Default "zero"
Enum"zero""previous"
granularitystringnon-empty

Time granularity for overtime series data

  • day - Daily data points
  • week - Weekly data points
  • month - Monthly data points
Default "day"
Enum"day""week""month"
llm_modelstringnon-empty

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

mentor_unique_idstring(uuid)
metricstringnon-emptyrequired

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_keystringnon-empty
providerstringnon-empty

Filter by AI provider

  • openai - OpenAI
  • anthropic - Anthropic
  • azure - Azure
  • google - Google
  • meta - Meta
  • other - Other
Enum"openai""anthropic""azure""google""meta""other"
show_overtimeboolean

Whether to include overtime series data in response

Default true
start_datestring(date)
usernamestringnon-empty

Filter by specific username - returns costs for this user only

curl -i -X GET \
  'https://docs.ibl.ai/_mock/apis/ibl/api/analytics/financial/?comparison_days=1&date_filter=today&end_date=2019-08-24&fill_method=zero&granularity=day&llm_model=string&mentor_unique_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&metric=total_costs&platform_key=string&provider=openai&show_overtime=true&start_date=2019-08-24&username=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Successful financial metrics response with period-based cost data

Bodyapplication/json
metricstringrequired

The metric type that was requested

filtersobjectrequired
filters.​start_datestring
filters.​end_datestring
filters.​granularitystringrequired
filters.​comparison_daysinteger
filters.​platform_keystring
filters.​mentor_unique_idstring
filters.​usernamestring
filters.​providerstring
filters.​llm_modelstring
filters.​all_timeboolean
valuestring(decimal)^-?\d{0,15}(?:\.\d{0,5})?$required

Primary metric value (cost in USD)

percentage_changenumber or null(double)required

Percentage change vs comparison period (null if no comparison)

overtimeArray of objects(OvertimeData)required

Time series data for overtime visualization

overtime[].​datestringrequired

Date in YYYY-MM-DD format

overtime[].​valuestring(decimal)^-?\d{0,15}(?:\.\d{0,5})?$required

Cost value for this time period

period_infoobjectrequired
period_info.​start_datestring

Start date of analysis period

period_info.​end_datestring

End date of analysis period

period_info.​period_daysinteger

Number of days in period

period_info.​range_typestring

Type of date range (custom, default, all_time, etc.)

comparison_infoobjectrequired
comparison_info.​previous_period_countinteger

Number of days in comparison period

comparison_info.​previous_period_valuestring(decimal)^-?\d{0,15}(?:\.\d{0,5})?$

Cost value for comparison period

comparison_info.​comparison_startstring

Start date of comparison period

comparison_info.​comparison_endstring

End date of comparison period

comparison_info.​comparison_daysinteger

Number of comparison days

comparison_info.​recent_period_valuestring(decimal)^-?\d{0,15}(?:\.\d{0,5})?$

Cost value for current period

Response
application/json

Response for total_costs metric.

{
  "metric": "total_costs",
  "filters": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "granularity": "day",
    "comparison_days": 10
  },
  "value": 45.789,
  "percentage_change": 15.2,
  "overtime": [
    { … },
    { … },
    { … },
    { … },
    { … }
  ],
  "period_info": {
    "start_date": "2025-01-01",
    "end_date": "2025-01-31",
    "period_days": 31,
    "range_type": "custom"
  },
  "comparison_info": {
    "previous_period_count": 10,
    "previous_period_value": 39.654,
    "comparison_start": "2024-12-22",
    "comparison_end": "2024-12-31",
    "comparison_days": 10,
    "recent_period_value": 45.789
  }
}

analytics_financial_details_retrieve

Request

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
  1. 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
  2. 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
}
``
Security
PlatformApiKeyAuthentication
Query
date_filterstringnon-empty
  • today - Today only
  • 7d - Last 7 days
  • 30d - Last 30 days
  • 90d - Last 90 days
  • all_time - All time
  • custom - Custom date range
Default "today"
Enum"today""7d""30d""90d""all_time""custom"
end_datestring(date)
group_bystringnon-emptyrequired

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"
limitinteger[ 1 .. 100 ]
Default 20
llm_modelstringnon-empty
mentor_unique_idstring(uuid)
metricsstringnon-empty

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

Default "total_cost"
pageinteger>= 1
Default 1
platform_keystringnon-empty
providerstringnon-empty
searchstring
start_datestring(date)
usernamestringnon-empty
curl -i -X GET \
  'https://docs.ibl.ai/_mock/apis/ibl/api/analytics/financial/details/?date_filter=today&end_date=2019-08-24&group_by=provider&limit=20&llm_model=string&mentor_unique_id=497f6eca-6276-4993-bfeb-53cbbbba6f08&metrics=total_cost&page=1&platform_key=string&provider=string&search=string&start_date=2019-08-24&username=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json
pageintegerrequired
limitintegerrequired
total_pagesintegerrequired
total_recordsintegerrequired
rowsany
total_coststring(decimal)^-?\d{0,15}(?:\.\d{0,5})?$
metricsArray of objects(MetricInfo)
Response
application/json
{
  "page": 0,
  "limit": 0,
  "total_pages": 0,
  "total_records": 0,
  "rows": null,
  "total_cost": "string",
  "metrics": [
    { … }
  ]
}

analytics_financial_invoice_retrieve

Request

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:

{
  "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": [...]
  }
}
Security
PlatformApiKeyAuthentication
Query
end_datestring(date)

End date for billing period (defaults to today)

include_breakdownboolean

Whether to include provider and mentor breakdown

Default true
platform_keystring[ 1 .. 255 ] characters

Platform key to filter by (optional, required for platform admins)

start_datestring(date)

Start date for billing period (defaults to 30 days ago)

usernamestring[ 1 .. 255 ] characters

Username to generate invoice for (optional)

curl -i -X GET \
  'https://docs.ibl.ai/_mock/apis/ibl/api/analytics/financial/invoice/?end_date=2019-08-24&include_breakdown=true&platform_key=string&start_date=2019-08-24&username=string' \
  -H 'Authorization: YOUR_API_KEY_HERE'

Responses

Bodyapplication/json
entityobject(Entity)required

Entity information for the invoice.

entity.​typestring(EntityTypeEnum)
  • user - user
  • platform - platform
  • global - global
Enum"user""platform""global"
entity.​usernamestring
entity.​platform_keystring
entity.​platform_namestring
entity.​display_namestringrequired
billing_periodobject(BillingPeriod)required

Billing period information.

billing_period.​start_datestring(date)required
billing_period.​end_datestring(date)required
billing_period.​daysintegerrequired
summaryobject(Summary)required

Summary metrics for the invoice.

summary.​total_coststring(decimal)^-?\d{0,9}(?:\.\d{0,3})?$required
summary.​total_sessionsintegerrequired
summary.​active_usersintegerrequired
summary.​cost_per_sessionstring(decimal)^-?\d{0,9}(?:\.\d{0,3})?$required
breakdownobject(Breakdown)

Detailed breakdown of costs.

Response
application/json
{
  "entity": {
    "type": "platform",
    "platform_key": "web-app",
    "platform_name": "Web Application",
    "display_name": "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": [ … ]
  }
}

career

Operations

catalog

Operations

core

Operations

credentials

Operations

custom-domains

Operations

features

Operations

media

Operations

notifications

Operations

scim

Operations

commerce

Operations

recommendations

Operations

reports

Operations

skills

Operations
Copyright © ibl.ai | support@iblai.zendesk.com