Scenario Admin Analytics

Scenario Admin Analytics

Overview

Turn Scenario MCP usage data into answers, CSV, Markdown, a PDF with charts, or an offline dashboard. All Scenario data collection stays on MCP. No direct API, SDK, browser scraping, or credentials in reporting scripts. Use the scenario skill for connection setup. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

Resolve the customer through teams_list and, when needed, projects_list({team_id}). Reuse the user's selected scope. If several names match, ask using the discovered choices; unattended, use the task's explicit team/project ID pair, otherwise stop and list the choices. Never choose the first silently. For an organization-wide request, use scope:"team" with an accessible context project. This covers projects accessible to the credential, not additional access rights. For a project use scope:"project" (default); project_id supplies authentication context and the default analytics filter. project_ids selects other projects within that team and cannot accompany scope:"team". Deduplicate selected IDs. Do not add a team total to its project subtotals or sum project unique-user counts.

Quick reference

Discover the current schema with scenario_tools_search({query:"usage",limit:1}) when missing or stale. Normally call visible usage directly. If catalog-only, use scenario_tool_execute_read({name:"usage",parameters:{...}}), never arguments. A host may retain an older direct signature after deployment: if the fresh catalog exposes missing fields, use that same read executor with its schema or reconnect. An old host signature does not establish a missing capability. Ground calls in the public usage reference and live catalog.

Always set both dates. Bounds are inclusive: a complete March ends at 2026-03-31T23:59:59.999Z. State UTC buckets. For an undated question assume the last 30 complete days; for "last three months" assume the last three complete calendar months, stating the window. An undated API call defaults to 31 days, not lifetime. Current-day figures are provisional. The API enforces its range limit; do not invent a fixed cap. If it rejects a large range, split into non-overlapping inclusive windows, retain each source, and combine additive measures without summing unique-identity counts.

Begin with summary JSON; add include:["modelUsages.daily","entities"] for reports. Time buckets may be finer than daily for short ranges; aggregate by timestamp then UTC day, rejecting duplicate timestamps. activity is paginated in batches of at most 100 via activity_offset; follow the returned next offset, not guessed completeness. Summaries repeat on activity pages: count them once. Avoid activity for ordinary rankings.

Accounting and confidence

totals.totalCU sums consumption[].value, already after discounts. Raw consumption[].total equals value + discount, before discounts. Model totalCU sums time-bucket cost, also already after discounts: never subtract discount again. API-key CU is a subset. Preserve decimals, zeros, fully discounted rows, and negatives. Jobs measure model executions, not successful assets.

Validate echoed scope and dates; check consumption against overall CU, time buckets against model summaries, and per-user model sums against the unfiltered models. The scope echo records applied filters; it does not prove access to every customer project. State established scope and results directly. Do not carry an old "unverified consumption" warning onto validated data.

Model series measure generation activity and exclude separately recorded refunds and non-model operations. Consequently model CU need not equal overall consumed CU. Show the measured difference without asserting its cause; inspect usage sections if an explanation is requested. Never allocate it to models, sum overlapping usage-type categories, or substitute job billing snapshots for consumption. If a check fails, withhold only the affected attribution, report the exact mismatch, and investigate through MCP.

For user/model matrices, collect one same-scope, same-period usage query per consumption[].userId, including zero or negative rows. Never join independent user and model summaries by proportion. Reconcile all model CU and jobs before claiming complete coverage; if identities are missing, investigate MCP identity/activity metadata rather than inventing attribution. Resolve names through returned entities; if names are missing and the recipient needs identifiable users, discover team_members_list and join its returned email by ID. Retain stable IDs internally, and distinguish API identities when metadata identifies them. Unknown identity type stays unknown. If "most used" has no stated metric, rank by jobs and show CU; an explicit CU request ranks by CU. Break ties deterministically by stable ID. Top-N rows include both metrics.