Usage and pricing

See what your models did, what that would cost at API rates, and where your limits are.

Usage in the Synoec sidebar shows your plans, API budgets and local models, and how each has been used over time. It combines Synoec’s own request receipts, what providers report about your accounts, local session logs, and token value at configured or published API rates. These are kept separate: an estimate is never your bill.

Three kinds of connection

Kind	Examples	Its limit comes from	Composer wheel
Subscription	Claude or Codex sign-in, Cursor	The plan, reported as a percentage. Budgets ignore it.	The provider’s percent
API	An Anthropic or Gemini API key, a hosted endpoint	A weekly, monthly or On-Demand budget you set	Percent of your budget, or Unlimited until you set one
Local	Ollama, any loopback, private-network or .local address	Nothing: unlimited, with tokens still tracked	An unlimited mark

Read the Usage surface

Tab	Shows
Overview	Usage over time, then connection cards grouped as Subscriptions, API and Local
Details	Recorded tokens, API-rate value, activity, coverage and Context saved by provider
Models	Configured and recorded models, including ones with no activity yet

Usage over time switches between Tokens, Dollars and % used, groups by Provider or Profile, and covers 30, 60, 90 or 180 days. A range longer than your history starts where the history starts, and the axis says so. Click a legend entry to leave it out or put it back, or only to show just that one. Work done outside Synoec has no Profile and appears as Outside Synoec.

History is one record per connection and day, kept in ~/.synoec/cache/usage-history/ with no expiry, so it grows as you use Synoec. It holds counters and labels, never content. It starts from what already exists: Cursor’s dashboard days, Codex’s account report and local history, and token counts from local Claude Code sessions (~/.claude/projects), read only when a Claude connection exists. Prompts and replies in those sessions are never kept. Sources that overlap are not added: an account’s report replaces what the logs say for that day, unless it reads lower. Claude reports only its current percent, so % used starts the first day it was read.

Details keeps the Activity scope toggle: All recorded activity (account history plus Synoec receipts, overlaps counted once) or Synoec only (direct Synoec requests in this workspace).

Implied plan cost

A subscription card shows what your use of the plan is worth: its monthly price, scaled to its longest reported window, times the percent used, and that over the window’s tokens per million. It is always an estimate, because providers do not publish how a percentage maps to tokens. The price comes from the plan name the provider reports, or from Plan price per month on the card, which overrides it. A plan with no single price, such as Claude’s max at $100 or $200, shows no implied cost until you enter one.

Values computed from rates carry the label Estimated · not your bill. Missing counters show as unknown or Partial pricing, never as zero. Under Codex history, Compare monthly plan fees compares 30-day API value with common plan prices — a comparison, not billed savings.

Each connection shows what its provider actually reports. Quota windows, provider dollar limits, organization pools and your budget become rings of percent used. A connection with no limit shows spend for its billing period when known, otherwise API-rate value of Synoec requests over the last 30 days (marked ~).

Context saved is an estimate of what Synoec’s own context reduction saved, separate from what provider caching saved. The card lists input avoided from history (long tool results shortened, old tool output cleared, earlier turns summarized) apart from input avoided by loading tools on demand, which repeats on nearly every request. Input a request omitted is capped at what the model could have accepted and scaled from the planner’s local count to provider-reported tokens. Omitted input is older prefix, so it is priced as a cache read once the request read the cache, and at that request’s own input mix before then. Input omitted only so a request fits the context window claims no saving.

Reduction can also cost money: when a tool list, summary or shortened result changes the start of a request, the provider’s prompt cache misses. A request that reads less cache than the one before it after such a change has the lost cache taken off the saving. This counts the cache already held, so it is a floor, and the net value can be negative. Agent runtimes such as Cursor report one total across a run’s model calls, so their reductions stay in planner units and are never scaled by that total; an unpriced request claims no provider tokens. The calculation lists what each step contributed, how many compaction attempts were kept and why each discarded one was thrown away, what compaction cost including discarded attempts, and how far the planner’s local count ran from the provider’s own count.

The planner keeps the start of a request stable so that cache is kept: the concise-response guidance it adds in a full window joins the presentation tail, the date there is fixed for a turn, and a turn’s own tool results are kept inline until a turn ends or the request would not fit. The ratio between the planner’s count and the provider’s is remembered per model in estimator-calibration.json under the workspace runtime, so a restarted engine does not start from the raw estimate, which reads about twice the provider’s count and once compacted a half-empty window. A compaction summary is asked for with the chat’s own prefix and the instruction last, so a local model reads it from its cache rather than from cold.

In a thread, the Context card lists what each step left out of the last request, how much of that was needed just to fit the window, and the thread’s compaction attempts with the reason any was discarded. These figures are the planner’s local estimate, not provider counts.

Composer usage

Under the composer, beside the model name, one small wheel shows the chat model’s connection. Its colored arc is what is left of a plan’s tightest limit or of your budget, so a full ring is untouched. A hollow ring is a connection with no limit read or set yet. An API connection with no budget and a local model show an unlimited mark (∞). Hover to fan out the other connections in the Profile, and click a wheel for its breakdown: used and limit, reset or period, credits and spend. An API connection’s breakdown also sets, changes or removes its budget.

The reply that closes a request ends with a line holding Copy and the request’s usage, shown on hover, such as 3,850 tokens · ~$0.0044. Tokens count input (cached input once) plus output, as Usage does. A trailing + means some steps are unpriced. When a background command or Specialist resumes the work, only the last reply carries the line, with the whole request’s total; reopened chats show the same.

Set a budget

Budgets are for API connections. Set one on the connection’s card in Usage → Overview, or by clicking its wheel under the composer: an amount, Weekly, Monthly or On-Demand, and when to warn. A week starts Monday 00:00 UTC, a month on the 1st. An On-Demand budget never resets, which suits prepaid credit: it counts what Synoec has settled at a price, and you raise it when you top up. Budgets count requests Synoec makes, not other apps using the same key.

At 100%, new requests on that connection are refused until the period resets or you raise the budget. A request already running can finish, so spend can go past the limit and read above 100%. Spend is what has settled, at a price you declared or otherwise the provider’s published rate, frozen when the request is sent. A model with neither is refused while a budget applies, because its cost could not be counted. Requests with no price stay out of the total and are counted beside it.

Plans and local models have no budget, and any wider budget ignores them. Setting one directly on such a connection is refused with the reason. Decision model requests report no usage and count as local, so budgets ignore them too.

A request can end without its provider reporting usage: it was cancelled, it failed, or the engine stopped mid-request. Synoec then closes its reservation as settled-unknown. Its tokens and cost are unknown, not zero, so they are in no total, and Overview says how many requests in the last 30 days ended this way. A closed request can have spent real money, so a budget’s percent is not a ceiling while that count is above zero. A request whose closure could not be proven, and one left open by an engine that stopped, closes six hours after it started.

synoec usage budget show
synoec usage budget set --scope connection --identity my-anthropic --usd 50 --warning 80
synoec usage budget remove --id <budget-id>

Organization and project budgets can still be set from the CLI. Token limits and --max-budget-usd refuse an agent runtime, because it cannot promise a stop.

synoec usage budget price --connection my-anthropic --model <model> \
  --input-usd-per-million 3 --output-usd-per-million 15 \
  --cache-read-usd-per-million 0.3 --cache-write-usd-per-million 3.75

See for how reservations settle.

Configure rates

Without configuration, Synoec values Codex, Claude, Anthropic and Gemini usage at the first-party API rates in the bundled estimator, whether the connection is a subscription or an API key. A request that ran on Fast uses the published Fast rate; with none published it uses the base rate and is marked partial. Claude’s one-hour cache writes use their own rate, and a price change a provider has announced with a date applies from that day. Codex’s reported cache writes count as cache-write input, priced like every other adapter’s.

Cursor usage is valued from Cursor’s own price page. If you have Cursor requests, reading Usage checks that public page at most once a day and sends no credential. A page Synoec cannot read leaves the last good rates in force, with a dated copy bundled in the app as the floor. A request uses the rates in force when it ran, and the calculation names the date of those rates. Rates more than 30 days old at the time of a request are marked partial. A model the page does not list, such as Auto, stays unpriced. These figures exclude Cursor’s Teams token rate, regional data-residency uplift and legacy Max Mode surcharge.

Everything else — custom endpoints, Bedrock, gateways — needs a rate sheet: one YAML file per adapter in pricing/<adapter>.yaml under your Synoec home (normally ~/.synoec/pricing/). A sheet takes precedence over published rates, including Cursor’s, and its rates apply at any speed and cache lifetime.

# Illustrative rates, not a current price list.
version: 1
adapter: openai-compatible
revision: "example"
connections:
  - connection: example-api
    channel: api
    cycleDay: 15
    tokenCost: rates
    models:
      - model: example-model
        input: "2"
        output: "8"
        cacheRead: "0.2"
        cacheWrite: "3"

Rates are quoted USD per million tokens, as strings. Use exact connection and model IDs from Usage. The bundled Usage Pricing Skill can edit these files for you. Refresh reloads them.

synoec usage pricing show
synoec usage pricing validate

Subscription plan fee

For a flat-fee subscription, record the monthly plan price. Synoec uses it to compare plan value in the Usage views.

synoec usage pricing plan codex 200
synoec usage pricing plan codex clear

The plan is written to that adapter’s pricing file. A file you have edited with comments is left alone; edit it directly instead.

Account reporting

Codex reports account history through its signed-in account, and Codex history can also read local Codex sessions on this computer.

A Claude account connection reports its plan’s five-hour session and weekly limits (and any model-scoped weekly limit), plus extra-usage spend when the plan has it. Reading them sends no prompt.

Cursor usage comes only from its dashboard. In the desktop app, Cursor sign-in opens in a Synoec window titled Sign in to Cursor, and that one sign-in stores both the SDK key and the dashboard session. For a connection signed in another way, open its Advanced provider settings → Usage reporting and choose Connect dashboard, using the same Cursor account as the connection. Your SDK sign-in is unchanged. Until the dashboard is connected, Usage says so instead of showing account data.

Each usage read can start a short-lived reporting host, so the last result is kept on disk under an account identity. Account-backed connections use their account reference. Key connections, such as Cursor, use a digest of the stored key and dashboard session, so reusing a connection name with another key never shows the old account’s numbers.

synoec auth reporting login --connection my-cursor --secret-stdin
synoec auth reporting status --connection my-cursor
synoec usage --refresh-accounts
synoec auth reporting logout --connection my-cursor

Pipe the reporting key or Cursor dashboard cookie on stdin; never put it in arguments, YAML or prompts. Account history may include other apps and machines; it is never added to Synoec receipt totals.

Inspect from the CLI

synoec usage
synoec usage --connection CursorWork --json
synoec usage --refresh-accounts

Limits

• Estimates use API rates; subscription bills, quotas and credits are reported separately and never added together.
• Local Codex history covers only this computer and can include several accounts.
• Account reporting on Windows is unavailable; local receipts and pricing still work.
• Receipts store tokens, not prices. API value is worked out when you read it, so editing a rate sheet changes past estimates as well as new ones. Published rates with an effective date do not.
• Long-context, tool and data-residency surcharges are not modelled.
• Purging a thread keeps its usage in totals. Synoec keeps one row per model request: the input, output, cache-read and cache-write counters, any further counters pricing reads, the date, provider, connection, model, speed and outcome, and any frozen cost. It keeps no thread, title, prompt or time of day, so these requests appear under Purged threads with no project, profile or context savings.
• Requests from threads purged before 0.8.46 left no such row and cannot be restored: their receipts were deleted, and the admission ledger kept no cache split or model to value them with. Totals for that period are lower than what ran.

Related

• Shared pricing owner
• Providers and models

Decisions behind this page: 0161, 0162, 0184, 0221, 0247, 0248, 0250, 0251, 0266 — see the decisions index.