AI usage
AI usage is what your people and agents did with AI tools: spend, tokens, requests and sessions, by team, person, provider and model. It’s the data behind the AI screens in the app.
There’s no REST endpoint for AI usage. Read it through the MCP server. AI usage is observed data, so it’s always live; scenarios don’t apply.
query_analytics
The general analytics tool. AI metrics use dataSource: "ACTUAL". The numbers match the AI spend screens.
| Metric | What it is | Needs |
|---|---|---|
AI_COST | AI spend attributed in the window, in the reporting currency | A financial view permission |
AI_TOKENS | Tokens reported by providers | — |
AI_REQUESTS | Requests reported by providers | — |
AI_SESSIONS | AI sessions | — |
AI dimensions: PROVIDER, MODEL, AI_USE_CATEGORY, AI_BUSINESS_FUNCTION, AI_ACTIVITY_TYPE, AI_AGENT. They combine with TEAM, EMPLOYEE, PROJECT, DATE and the other workforce dimensions.
| Question | Arguments |
|---|---|
| AI spend by provider | metrics: ["AI_COST"], dimensions: ["PROVIDER"] |
| AI spend by team, by month | metrics: ["AI_COST"], dimensions: ["TEAM", "DATE"], timeGranularity: "MONTH" |
| Heaviest Copilot users | metrics: ["AI_TOKENS", "AI_REQUESTS"], dimensions: ["EMPLOYEE"], filters: [{ "dimension": "PROVIDER", "operator": "EQ", "values": ["github_copilot"] }] |
Other AI tools
| Tool | Returns |
|---|---|
get_ai_adoption_summary | Organisation-wide adoption: people using AI in the last 30 days, weekly active users, tools in use, idle licensed seats and their monthly cost, and teams ranked by adoption |
get_hybrid_workforce_summary | Employees, contractors and agents with headcount and cost, AI share of the bill, and AI spend against the monthly AI budget cap. Needs a financial view permission. |
get_ai_security_metrics | Shadow AI use, data loss prevention signals and customer-data exfiltration events, by provider, subject or team |
mark_my_ai_sessions_as_project | Attributes the caller’s own AI sessions to a project |
add_ai_agent, update_ai_agent, delete_ai_agent | Manage AI agents in the workforce |
See the tool catalogue for arguments.
Webhooks
Changes to AI agents and AI policies send ai_agent, agent_policy and ai_policy events. See Webhooks.
Related
- MCP server: connecting, permissions and every tool.
- See where your AI spend goes: the AI spend screens.