Atlas usage events are the single source of truth for billing and compliance. The schema below never changes without a migration notice.
Why log every call
Usage events are the ledger that binds together identity, consent, budgets, and provenance. Finance uses them to reconcile invoices, compliance uses them to answer subpoenas, and engineers use them to debug latency or vendor issues.
Field reference
Use this table to map Atlas telemetry into your warehouse or SIEM. The same fields power tracker dashboards and partner exports.
| Field | Description |
|---|---|
| event_id | Signed UUID for the tool call |
| ts_utc | UTC timestamp when the call finished |
| actor_id | Atlas user or bot ID |
| role | Actor role (Owner/Admin/Client/Bot) |
| office_id | Office or brokerage subdivision |
| tool_name | Canonical MCP tool identifier |
| vendor_name | Downstream vendor (Atlas default or marketplace) |
| model_name | LLM or automation model used |
| subject_ref | Workspace resource (transaction/item/file) touched |
| input_tokens | Tokens sent to the model |
| output_tokens | Tokens returned |
| input_bytes | Payload size in bytes |
| output_bytes | Response size in bytes |
| api_cost_usd | Raw vendor cost in USD |
| atlas_fee_usd | Atlas platform fee in USD |
| total_cost_usd | Sum of api_cost_usd + atlas_fee_usd |
| rate_bucket | Which budget bucket was decremented |
| rl_allowed | Whether the request passed rate limiting |
| rl_action | Action taken (pass, queue, deny) |
| latency_ms | Round-trip latency in milliseconds |
| cache_hit | True if cache satisfied the request |
| success | True if the tool completed successfully |
| artifact_uri | Pointer to resulting artifact (PDF, JSON, etc.) |
| consent_scopes | Scopes attached to this call |
| signature | Cryptographic signature for tamper detection |
Example JSON event
Here is a realistic event for the rental comps tool. Copy it into your contract tests to ensure your ingestion pipeline handles every field.
{
"event_id": "evt_mcp_240124",
"ts_utc": "2025-01-24T15:18:04Z",
"actor_id": "agent_204",
"role": "Agent",
"office_id": "denver_team_a",
"tool_name": "generate_rental_comps_pdf",
"vendor_name": "atlas_default",
"model_name": "gpt-4o-mini",
"subject_ref": "txn_D455:item_summary",
"input_tokens": 980,
"output_tokens": 1320,
"input_bytes": 28100,
"output_bytes": 40220,
"api_cost_usd": 0.58,
"atlas_fee_usd": 0.17,
"total_cost_usd": 0.75,
"rate_bucket": "denver_team_a.daily",
"rl_allowed": true,
"rl_action": "pass",
"latency_ms": 1980,
"cache_hit": false,
"success": true,
"artifact_uri": "atlas://artifacts/txn_D455/rental-comps-2025-01-24.pdf",
"consent_scopes": [
"mls.read",
"atlas.data"
],
"signature": "0x92acff932..."
}Downstream consumers
Finance: join event_id to invoices, roll up cost by workspace or office.
Security: stream events into your SIEM to detect anomalous usage.
Product: slice by tool or vendor to prioritize new guardrails.
- Finance & RevOps → reconcile cost and apply markups.
- Security → watch for unusual scopes or actors.
- Product → spot hot tools, latency regressions, and cache wins.