Analytics API

The Analytics API provides aggregated views of your cost data, optimized for reporting and dashboards.

Base URL

https://api.infraprism.com/v1/analytics

Authentication

Include your API key in the Authorization header:

curl https://api.infraprism.com/v1/analytics/costs \
  -H "Authorization: Bearer ip-your-api-key"

Endpoints

Cost Summary

Get aggregated costs over a time period.

GET /v1/analytics/costs

Query Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date (YYYY-MM-DD)
`end_date`	string	Yes	End date (YYYY-MM-DD)
`entity_type`	string	No	Filter by entity type
`entity_id`	string	No	Filter by entity ID
`model`	string	No	Filter by model
`group_by`	string	No	Group results (see below)
`tags`	string	No	Filter by tags (key:value,key:value)

Group By Options:

entity - Group by entity_type and entity_id
model - Group by model
day - Group by day
week - Group by week
month - Group by month
tags.{key} - Group by a specific tag

Example Request:

curl "https://api.infraprism.com/v1/analytics/costs?start_date=2025-01-01&end_date=2025-01-31&entity_type=customer&group_by=entity" \
  -H "Authorization: Bearer ip-..."

Response:

{
  "data": [
    {
      "entity_type": "customer",
      "entity_id": "acme-corp",
      "total_cost": 523.45,
      "total_events": 15234,
      "total_input_tokens": 2500000,
      "total_output_tokens": 8500000,
      "avg_latency_ms": 1150
    },
    {
      "entity_type": "customer",
      "entity_id": "globex",
      "total_cost": 312.20,
      "total_events": 8921,
      "total_input_tokens": 1200000,
      "total_output_tokens": 5100000,
      "avg_latency_ms": 980
    }
  ],
  "summary": {
    "total_cost": 835.65,
    "total_events": 24155,
    "period": {
      "start": "2025-01-01",
      "end": "2025-01-31"
    }
  }
}

Cost Time Series

Get costs over time for charting.

GET /v1/analytics/costs/timeseries

Query Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date
`end_date`	string	Yes	End date
`interval`	string	No	Interval: `hour`, `day`, `week`, `month` (default: `day`)
`entity_type`	string	No	Filter by entity type
`entity_id`	string	No	Filter by entity ID

Example Request:

curl "https://api.infraprism.com/v1/analytics/costs/timeseries?start_date=2025-01-01&end_date=2025-01-31&interval=day" \
  -H "Authorization: Bearer ip-..."

Response:

{
  "data": [
    {
      "timestamp": "2025-01-01T00:00:00Z",
      "cost": 12.34,
      "events": 523
    },
    {
      "timestamp": "2025-01-02T00:00:00Z",
      "cost": 15.67,
      "events": 612
    }
  ],
  "interval": "day"
}

Model Usage

Get usage breakdown by model.

GET /v1/analytics/models

Query Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date
`end_date`	string	Yes	End date
`entity_type`	string	No	Filter by entity type
`entity_id`	string	No	Filter by entity ID

Response:

{
  "data": [
    {
      "model": "gpt-4o",
      "provider": "openai",
      "total_cost": 450.00,
      "total_events": 10000,
      "total_input_tokens": 2000000,
      "total_output_tokens": 6000000,
      "avg_latency_ms": 1200,
      "percentage_of_total": 54.2
    },
    {
      "model": "gpt-4o-mini",
      "provider": "openai",
      "total_cost": 85.00,
      "total_events": 25000,
      "total_input_tokens": 5000000,
      "total_output_tokens": 12000000,
      "avg_latency_ms": 450,
      "percentage_of_total": 10.2
    }
  ]
}

Entity Leaderboard

Get top entities by cost.

GET /v1/analytics/entities/top

Query Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date
`end_date`	string	Yes	End date
`entity_type`	string	No	Filter by entity type
`limit`	integer	No	Number of results (default: 10, max: 100)
`order`	string	No	`desc` (default) or `asc`

Response:

{
  "data": [
    {
      "entity_type": "customer",
      "entity_id": "acme-corp",
      "total_cost": 523.45,
      "total_events": 15234,
      "rank": 1
    },
    {
      "entity_type": "customer",
      "entity_id": "globex",
      "total_cost": 312.20,
      "total_events": 8921,
      "rank": 2
    }
  ]
}

Sessions

Get session-level analytics.

GET /v1/analytics/sessions

Query Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date
`end_date`	string	Yes	End date
`entity_type`	string	No	Filter by entity type
`entity_id`	string	No	Filter by entity ID
`limit`	integer	No	Number of results

Response:

{
  "data": [
    {
      "session_id": "550e8400-e29b-41d4-a716-446655440000",
      "entity_type": "customer",
      "entity_id": "acme-corp",
      "started_at": "2025-01-15T10:00:00Z",
      "ended_at": "2025-01-15T10:15:00Z",
      "turn_count": 5,
      "total_cost": 0.0234,
      "total_tokens": 3500
    }
  ],
  "summary": {
    "total_sessions": 1523,
    "avg_turns_per_session": 4.2,
    "avg_cost_per_session": 0.0185
  }
}

Anomalies

Get detected anomalies.

GET /v1/analytics/anomalies

Query Parameters:

Parameter	Type	Required	Description
`start_date`	string	Yes	Start date
`end_date`	string	Yes	End date
`entity_type`	string	No	Filter by entity type
`status`	string	No	`active`, `resolved`, `dismissed`

Response:

{
  "data": [
    {
      "id": "anomaly_123",
      "detected_at": "2025-01-15T10:30:00Z",
      "entity_type": "customer",
      "entity_id": "acme-corp",
      "type": "cost_spike",
      "severity": "high",
      "description": "Cost increased 340% compared to 7-day average",
      "expected_value": 12.50,
      "actual_value": 55.00,
      "status": "active"
    }
  ]
}

Compare Periods

Compare two time periods.

GET /v1/analytics/compare

Query Parameters:

Parameter	Type	Required	Description
`period1_start`	string	Yes	First period start
`period1_end`	string	Yes	First period end
`period2_start`	string	Yes	Second period start
`period2_end`	string	Yes	Second period end
`entity_type`	string	No	Filter by entity type
`entity_id`	string	No	Filter by entity ID

Response:

{
  "period1": {
    "start": "2025-01-01",
    "end": "2025-01-15",
    "total_cost": 450.00,
    "total_events": 12000
  },
  "period2": {
    "start": "2024-12-16",
    "end": "2024-12-31",
    "total_cost": 380.00,
    "total_events": 10500
  },
  "changes": {
    "cost_change": 70.00,
    "cost_change_percent": 18.4,
    "events_change": 1500,
    "events_change_percent": 14.3
  }
}

Filtering by Tags

Use the tags parameter to filter by custom tags:

# Single tag
curl "...?tags=feature:chatbot"

# Multiple tags (AND)
curl "...?tags=feature:chatbot,env:production"

Response Formats

CSV Export

Add format=csv to get CSV output:

curl "https://api.infraprism.com/v1/analytics/costs?...&format=csv" \
  -H "Authorization: Bearer ip-..." \
  -o costs.csv

Python Example

import requests
from datetime import datetime, timedelta

API_KEY = "ip-your-api-key"
BASE_URL = "https://api.infraprism.com/v1"

def get_customer_costs(start_date: str, end_date: str):
    response = requests.get(
        f"{BASE_URL}/analytics/costs",
        headers={"Authorization": f"Bearer {API_KEY}"},
        params={
            "start_date": start_date,
            "end_date": end_date,
            "entity_type": "customer",
            "group_by": "entity",
        },
    )
    response.raise_for_status()
    return response.json()

# Get last 30 days of customer costs
end = datetime.now()
start = end - timedelta(days=30)
data = get_customer_costs(
    start.strftime("%Y-%m-%d"),
    end.strftime("%Y-%m-%d"),
)

for customer in data["data"]:
    print(f"{customer['entity_id']}: ${customer['total_cost']:.2f}")

Next Steps

REST API - Full REST API reference
Python SDK - SDK documentation
Cost Attribution - Tagging strategies