Appearance
AI usage
There's no /api/v1/ai-usage REST endpoint. AI data ships via two surfaces, both designed for the actual workloads asking the questions.
| Surface | Use it when |
|---|---|
| MCP server | An LLM (Claude, ChatGPT, internal tooling) is asking the question — natural language in, structured tool result out |
| GraphQL | A first-party UI or back-end service needs typed queries with field-level selection |
This page summarises what's exposed via MCP for AI data, and what GraphQL operations underlie it.
MCP tools for AI data
The MCP server exposes three read tools dedicated to AI usage. All take an optional startDate and endDate; defaults are "last 3 months".
get_ai_usage_summary
Total AI spend grouped by system (provider).
Arguments
| Name | Type | Default |
|---|---|---|
startDate | string (ISO date) | 3 months ago |
endDate | string (ISO date) | today |
Returns — a per-system breakdown with spend in the org's reporting currency, observed token totals, and seat counts.
get_ai_spend_by_team
Spend broken down by team, with adoption rate (fraction of team headcount actively using AI).
Arguments — same date window as above.
Returns — per-team spend, per-team adoption, and the team's parent in the hierarchy (so callers can roll up to cost centre).
get_ai_spend_by_person
Per-user drilldown, optionally filtered by system.
Arguments
| Name | Type | Default |
|---|---|---|
startDate | string (ISO date) | 3 months ago |
endDate | string (ISO date) | today |
system | string | (all) |
Returns — per-subject spend, the system that account is on, and the subject's primary team.
How the MCP authentication works
The MCP server uses OAuth 2.1 with PKCE — see API → MCP server for the full handshake. Once a tool call is authenticated, it inherits the calling user's Flowstate permissions. AI usage queries require AI_INSIGHTS_VIEW on the user's role.
What lives at GraphQL
If you're calling Flowstate from a first-party service rather than from a chat client, GraphQL is the typed access path. The relevant operations:
| Operation | What it returns |
|---|---|
aiSpendReconciliation(period, status, limit) | Provider-billing rows for a period, filtered by reconciliation status |
aiSpendReconciliationSummary(period) | Period totals — billed, observed, written off, residual |
aiProjectForecasts(organizationId) | Six-month forecast per project with confidence |
aiTeamForecasts(organizationId) | Six-month forecast per team |
aiForecastMonthlySeries(organizationId, monthsAhead, monthsBack) | Combined past-actuals + future-forecast time series |
fluencyRollup(scope, windowDays) | Per-competency, per-indicator scores for a scope |
fluencyTrend(scope, weeks, windowDays) | Weekly competency time series |
aiServiceAccounts(includeDeleted) | Service-account inventory with recent signal counts |
orgAiServices | Provider catalogue |
behaviouralSignals(filter, limit) | The behavioural-signal stream |
activePolicy, policyHistory(limit) | Active policy and version timeline |
GraphQL access uses the same API key format as the rest of the API — see Authentication.
Scenario support
Forecast queries operate on live data only. There's no scenario-scoped forecast — the model would need 90 days of telemetry on hypothetical staffing, which doesn't exist. If you want to model a counterfactual ("what does spend look like if we add 5 engineers to this project"), build the workforce side of the scenario in Workforce → Scenarios, then re-run the Forecast refresh against the activated plan.
The reconciliation, attribution, fluency and signals surfaces are likewise live-only. Scenarios are a workforce-modelling concept; AI telemetry is observed, not modelled.
Why no REST endpoint
REST endpoints in Flowstate are CRUD over editable entities — employees, teams, projects, allocations. AI data isn't a CRUD entity; it's a continuously-arriving stream of facts plus computed rollups. The shapes that matter to consumers (per-system summary, per-team breakdown, per-person drilldown) are tool-shaped, not resource-shaped. MCP is the right surface for "ask this question and get an answer" and that's how we ship it.
If you have a use case that genuinely needs REST — bulk export of raw sessions for a SOC 2 audit, for instance — open an issue. The data is there; we'll expose what makes sense.
See also
- MCP server — full protocol reference
- Insights → Attribution — the UI surface
- Insights → Spend reconciliation — the reconciliation queue
- Insights → Forecast — the projection model
- Insights → Fluency — the 3D fluency model