Docs / Reference / Data model

Data model

The records Token Controller keeps, and the rules that hold between them. For what the terms mean, see Concepts and the glossary.

Browse the docs

Getting started

Collect

Attribute

Account

Report

Self-hosting

Reference

Records

Record	What it holds
Organization	Cost source, attribution target, approval on or off, members and their roles, the team tree.
Team	A node in the team tree: a team, a department or the organization.
Person	A member. The smallest cost center. Belongs to one team at a time.
Project	Client label, tags, mapped repositories, ticket key pattern.
Ticket	Synced from a ticket system or created by hand. Optional parent ticket, optional assignee, optional size from the ticket system.
Token entry	Agent harness, optional agent name, model, tokens by kind, optional reported cost, list value, billed value, time range, summary, agent manager, postings, whether it arrived automatically or on a token sheet, status, evidence.
Posting	One share of a token entry on one cost object, with one cost kind.
Token sheet	One agent manager, one cadence period, the token entries that were not reported automatically. Submitted or late.
Cadence	The rhythm in which token sheets are due, set per project or organization by a people manager.
Token budget	Money a human has planned for a person, ticket, project or period.
Token forecast	Money predicted from past cost. Becomes a token budget when a person accepts it.
Telemetry event	One model call. Joins to token entries by session and message ID.
Cost source	One way a provider charges: subscription, seat, usage at API rates, API key, cloud marketplace or reseller.
Bill	A provider's figure for one period: gross, discount, credit, net, currency, cost source, revision.
Period	One calendar month, open or closed.
Cost sheet	The locked account of one closed period, adding up to the bill.
Rule	Ordered. Organization rules run before personal ones.

There is no agent record. An agent is whatever caused a token entry, described on the entry by agent harness, agent name and model.

Token entry status

Status	Meaning
Draft	Still on the machine, waiting for its token sheet.
Submitted	Counts in reports. Automatic token entries start here.
Approved	A people manager accepted it. Only used when approval is on.
Rejected	Sent back to its agent manager with a reason. Does not count until fixed.
Locked	Its period is closed.

Rules that always hold

Every cost has a cost center and a cost object.
The cost center comes from the token entry's agent manager. The cost object falls back from ticket to project to organization when nothing more specific matches.
No token entry without an agent manager.
One that has none shows as an error to people managers until someone takes it.
History stays as it was.
When an automation gets a new agent manager, or a person changes team or leaves, only future token entries follow the change. Past postings keep the agent manager and team they had.