Intelligence API

Base URL: http://localhost:8000 (development) or your production endpoint.

Prescriptive monetization endpoints — root cause, unit economics, what-if simulation, and revenue overlay ingest. Reads native FluxMeter usage/cost rollups from Redis; optional revenue from OpenMeter overlay or manual admin POST.

Auth: Most endpoints require X-API-Key (FLUXMETER_API_KEY). Admin endpoints require FLUXMETER_ADMIN_KEY. See api-reference.md.

Period format: YYYY-MM (UTC calendar month), matching billing query periods.

`GET /intelligence/root-cause`

Decompose spend change between two months by model, customer, and attribution dimensions.

Query parameters:

Parameter	Required	Description
`period`	yes	Current month (`YYYY-MM`)
`baseline_period`	yes	Comparison month (`YYYY-MM`)
`scope`	no	`global` (default) or `customer:{customer_id}`

curl -s "http://localhost:8000/intelligence/root-cause?period=2026-07&baseline_period=2026-06&scope=global" \
  -H "X-API-Key: $FLUXMETER_API_KEY" | jq .

Example response:

{
  "period": "2026-07",
  "baseline_period": "2026-06",
  "total_cost_usd": 140.0,
  "baseline_cost_usd": 100.0,
  "delta_usd": 40.0,
  "delta_pct": 40.0,
  "summary": "Cost +40.0% vs 2026-06. Top driver: model gpt-4o (72% of change).",
  "contributors": [
    {
      "dimension": "model",
      "key": "gpt-4o",
      "current_cost_usd": 100.0,
      "baseline_cost_usd": 60.0,
      "delta_usd": 40.0,
      "delta_pct": 66.7,
      "share_of_total_delta_pct": 100.0
    }
  ]
}

`GET /intelligence/unit-economics`

Per-customer revenue vs cost, margin, and rule-based recommendations.

Requires revenue data per customer (OpenMeter overlay or POST /intelligence/revenue/{customer_id}). Customers without revenue return status: unknown_revenue.

Query parameters:

Parameter	Required	Description
`period`	yes	Month to analyze (`YYYY-MM`)

curl -s "http://localhost:8000/intelligence/unit-economics?period=2026-07" \
  -H "X-API-Key: $FLUXMETER_API_KEY" | jq .

Example response:

[
  {
    "customer_id": "cust_a",
    "period": "2026-07",
    "revenue_usd": 500.0,
    "cost_usd": 620.0,
    "margin_usd": -120.0,
    "margin_pct": -24.0,
    "status": "loss",
    "recommendation": "Customer losing money — suggest plan upgrade or usage cap"
  },
  {
    "customer_id": "cust_b",
    "period": "2026-07",
    "revenue_usd": null,
    "cost_usd": 45.0,
    "margin_usd": null,
    "margin_pct": null,
    "status": "unknown_revenue",
    "recommendation": "Connect revenue (OpenMeter overlay or POST /intelligence/revenue)"
  }
]

`POST /intelligence/simulate`

What-if scenario simulation. Pure pricing math — no Redis writes.

Scenario types:

`scenario`	Required fields
`model_switch`	`input_tokens`, `output_tokens`, `from_model`, `to_model`; optional `monthly_occurrences` (default 1)
`prompt_reduction`	`cost_usd`, `input_reduction_pct`
`token_grant`	`cost_usd`, `grant_tokens`, `signup_lift_pct`, `avg_revenue_per_customer_usd`, `customer_count`

Model switch (e.g. GPT-4o → Claude)

curl -s -X POST "http://localhost:8000/intelligence/simulate" \
  -H "X-API-Key: $FLUXMETER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "model_switch",
    "input_tokens": 1000000,
    "output_tokens": 500000,
    "from_model": "gpt-4o",
    "to_model": "claude-sonnet-4",
    "monthly_occurrences": 1
  }' | jq .

Prompt reduction

curl -s -X POST "http://localhost:8000/intelligence/simulate" \
  -H "X-API-Key: $FLUXMETER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "prompt_reduction",
    "cost_usd": 800.0,
    "input_reduction_pct": 20
  }' | jq .

curl -s -X POST "http://localhost:8000/intelligence/simulate" \
  -H "X-API-Key: $FLUXMETER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "scenario": "token_grant",
    "cost_usd": 50.0,
    "grant_tokens": 100000,
    "signup_lift_pct": 5,
    "avg_revenue_per_customer_usd": 29.0,
    "customer_count": 200
  }' | jq .

Example response (model_switch):

{
  "scenario": "model_switch",
  "annual_savings_usd": 1234.56,
  "annual_profit_delta_usd": null,
  "notes": "Switch gpt-4o → claude-sonnet-4: $102.88/mo → $0.00/mo (+$102.88/mo)"
}

Returns 400 if required fields for the chosen scenario are missing.

`POST /intelligence/revenue/{customer_id}` (admin)

Manually set revenue for a customer/period when no billing overlay is connected.

Auth: Admin key (FLUXMETER_ADMIN_KEY)

Request body:

{
  "period": "2026-07",
  "revenue_usd": 500.0
}

curl -s -X POST "http://localhost:8000/intelligence/revenue/cust_a" \
  -H "X-API-Key: $FLUXMETER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period": "2026-07", "revenue_usd": 500.0}' | jq .

Response: 200 OK

{"status": "ok"}

`POST /intelligence/import/openmeter` (admin)

Import revenue events from an OpenMeter export payload. Non-revenue events are counted in ignored_rows.

Auth: Admin key

Query parameters:

Parameter	Required	Description
`period`	no*	Month (`YYYY-MM`); required if omitted from body

* period must appear in the JSON body or as a query parameter.

Request body:

{
  "period": "2026-07",
  "events": [
    {
      "subject": "revenue",
      "customerId": "cust_a",
      "value": 500.0
    }
  ]
}

curl -s -X POST "http://localhost:8000/intelligence/import/openmeter?period=2026-07" \
  -H "X-API-Key: $FLUXMETER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {"subject": "revenue", "customerId": "cust_a", "value": 500.0},
      {"subject": "usage", "customerId": "cust_a", "value": 1200}
    ]
  }' | jq .

Response: 200 OK

{
  "revenue_rows": 1,
  "ignored_rows": 1
}

`GET /intelligence/summary`

Prescriptive one-pager for Finance/CEO: root-cause headline plus list of unprofitable customers.

Query parameters:

Parameter	Required	Description
`period`	yes	Current month (`YYYY-MM`)
`baseline_period`	yes	Comparison month (`YYYY-MM`)

curl -s "http://localhost:8000/intelligence/summary?period=2026-07&baseline_period=2026-06" \
  -H "X-API-Key: $FLUXMETER_API_KEY" | jq .

Example response:

{
  "headline": "Cost +40.0% vs 2026-06. Top driver: model gpt-4o (72% of change). 1 customer(s) unprofitable in 2026-07.",
  "root_cause_summary": "Cost +40.0% vs 2026-06. Top driver: model gpt-4o (72% of change).",
  "loss_customers": [
    {
      "customer_id": "cust_a",
      "period": "2026-07",
      "revenue_usd": 500.0,
      "cost_usd": 620.0,
      "margin_usd": -120.0,
      "margin_pct": -24.0,
      "status": "loss",
      "recommendation": "Customer losing money — suggest plan upgrade or usage cap"
    }
  ]
}

Phase 6 — Intelligence v1.0 (3.1.0)

`GET /intelligence/pricing-recommendations`

Rule-based pricing actions with annual ROI (price increase, model switch).

curl -s "http://localhost:8000/intelligence/pricing-recommendations?period=2026-07" \
  -H "X-API-Key: $FLUXMETER_API_KEY" | jq .

`GET /intelligence/profitability`

Cross-customer margin overview, product breakdown, multi-month trend.

curl -s "http://localhost:8000/intelligence/profitability?period=2026-07&months=3" \
  -H "X-API-Key: $FLUXMETER_API_KEY" | jq .

`GET /intelligence/forecast`

Linear spend forecast vs budget (on_track | at_risk | over_budget | no_budget).

curl -s "http://localhost:8000/intelligence/forecast?period=2026-07&scope=global" \
  -H "X-API-Key: $FLUXMETER_API_KEY" | jq .

`GET /intelligence/report`

Finance/CEO export — format=json (default) or format=markdown.

curl -s "http://localhost:8000/intelligence/report?period=2026-07&baseline_period=2026-06&format=markdown" \
  -H "X-API-Key: $FLUXMETER_API_KEY"

`POST /intelligence/alerts/webhook` (admin)

Configure webhook for anomaly alerts (INTEL_COST_SPIKE, INTEL_MARGIN_LOSS, INTEL_FORECAST_RISK).

curl -s -X POST "http://localhost:8000/intelligence/alerts/webhook" \
  -H "X-API-Key: $FLUXMETER_ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://hooks.example.com/intel","secret":"whsec_..."}'

Or set env: FLUXMETER_INTEL_WEBHOOK_URL, FLUXMETER_INTEL_WEBHOOK_SECRET. Background worker polls every 300s.

Data sources

Source	Provides
FluxMeter native (Lite/Full ingest)	Usage, cost rollups, model/dim attribution
OpenMeter overlay	Revenue per customer via `/import/openmeter`
Manual admin POST	Revenue per customer via `/revenue/{customer_id}`

See also: api-reference.md · OpenAPI spec

Intelligence API

GET /intelligence/root-cause

GET /intelligence/unit-economics

POST /intelligence/simulate

Model switch (e.g. GPT-4o → Claude)

Prompt reduction

Token promo (signup grant)

POST /intelligence/revenue/{customer_id} (admin)

POST /intelligence/import/openmeter (admin)

GET /intelligence/summary

Phase 6 — Intelligence v1.0 (3.1.0)

GET /intelligence/pricing-recommendations

GET /intelligence/profitability

GET /intelligence/forecast

GET /intelligence/report

POST /intelligence/alerts/webhook (admin)

Data sources

`GET /intelligence/root-cause`

`GET /intelligence/unit-economics`

`POST /intelligence/simulate`

`POST /intelligence/revenue/{customer_id}` (admin)

`POST /intelligence/import/openmeter` (admin)

`GET /intelligence/summary`

`GET /intelligence/pricing-recommendations`

`GET /intelligence/profitability`

`GET /intelligence/forecast`

`GET /intelligence/report`

`POST /intelligence/alerts/webhook` (admin)