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
AI spend and usage questions go through the generic query_analytics tool — the same SQL analytics engine that powers the in-app report builder, so the numbers always agree with the AI spend pages. (The former dedicated tools get_ai_usage_summary, get_ai_spend_by_team and get_ai_spend_by_person were removed; they pre-dated the engine's AI metrics and computed their own, unreconcilable aggregates.) The MCP server page lists the fuller AI tool set, including get_ai_security_metrics and mark_my_ai_sessions_as_project.
AI metrics on query_analytics
All AI metrics use dataSource: "ACTUAL" and slice by any supported dimension — TEAM, EMPLOYEE, PROVIDER, MODEL, PROJECT, DATE, AI_USE_CATEGORY, and so on.
| Metric | Meaning | Permissions |
|---|---|---|
AI_COST | Attributed AI spend (session grain, reporting currency) | FINANCIALS_VIEW_* |
AI_SEAT_INVOICE_COST | Invoice/seat spend for catalogue-only vendors | FINANCIALS_VIEW_* (GraphQL) |
AI_TOKENS | Provider-reported token volume (input + output) across all capture modes | none |
AI_REQUESTS | Provider-reported request volume | none |
AI_SESSIONS | Telemetry session count | none |
Common shapes
- "What is our AI spend by provider?" —
metrics: ["AI_COST"],dimensions: ["PROVIDER"] - "Which teams spend the most on AI?" —
metrics: ["AI_COST"],dimensions: ["TEAM"],sort: "AI_COST",order: "DESC" - "Who uses Copilot the most?" —
metrics: ["AI_TOKENS", "AI_REQUESTS"],dimensions: ["EMPLOYEE"],filters: [{"dimension": "PROVIDER", "operator": "EQ", "values": ["github_copilot"]}]
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