Models and accounts

Usage

What has been spent, grouped

On this page(4 sections)

What was spent, grouped
Measure every account's plan limits again
Whether this account's session window can be reopened now
Reopen this account's session window now

One read: the spending record over a range of days, grouped finely enough that every cost screen is a rearrangement of it rather than a second call.

GET/usage/rollupWhat was spent, grouped

The spending record over a range of days, grouped by day, provider, account and model. Everything a cost screen shows is a rearrangement of this one answer, so nothing needs a second call. Read-only: rows are written by the sandbox as turns end, which is what makes it worth trusting.

What you send

Field	Type	Where
`from`First day to include, as YYYY-MM-DD…	string	query
`to`Last day to include, as YYYY-MM-DD…	string	query

What comes back

Field	Type
`rows`Spending grouped by day, provider, account,…	object[]
`day`The day, as YYYY-MM-DD in UTC	string
`provider`Which model provider	string
`account`Which account	string
`model`Which model	string
`harness`Which agentic loop	string
`conversationId`Which conversation	string
`turns`Turns in this group	number
`inputTokens`Uncached input tokens, excluding cache reads…	number
`outputTokens`Tokens received	number
`cacheReadTokens`Tokens served from cache	number
`cacheCreationTokens`Tokens written to cache	number
`costUsd`What the group cost, in dollars	number
`costKnown`False when the cost includes unpriced…	boolean
`durationMs`Time spent, in milliseconds	number

Try itanswered in this tab

curl

curl "$SANDBOX/usage/rollup" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.usage.rollup();

POST/usage/plan-limits/refreshMeasure every account's plan limits again

Reads how full each connected account's plan limits are, for every provider, and records it. Forced, it measures even accounts read a moment ago, which is the right thing when a plan was just changed and the question is whether the number on screen is still true. Answers with the accounts it could not read because the provider is rate-limiting them, and when each may be asked again: those keep the reading they already had, so a number that does not move is explained rather than silent.

What you send

Field	Type	Where
`force`Measure again even if a reading…	boolean	body

What comes back

Field	Type
`ok`	true
`held`Accounts whose plan limits could not…	object[]
`provider`Which provider is holding the read…	string
`account`The account as its provider's list…	string
`resumesAt`Unix seconds: when this account may…	number

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/usage/plan-limits/refresh" \
  -H "x-intentic-control: $INTENTIC_TOKEN" \
  -H "content-type: application/json" \
  -d '{"force":false}'

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.usage.refreshPlanLimits({
  "force": false
});

GET/usage/limit-reset/{account}Whether this account's session window can be reopened now

Asks the provider whether it will reopen this account's spent session window immediately, which some plans grant once a week. Only worth asking about an account that has actually been refused: the answer is the provider's judgement at this moment, it is not cached, and an account with no such grant answers plainly that it has none.

What you send

Field	Type	Where
`account`requiredWhich account	string	address

What comes back

Field	Type
`available`Whether the provider will reopen this…	boolean
`reason`Why not, in the provider's own…	string
`nextAvailableAt`When the next reset may be…	number
`weeklyResetsAt`When the weekly allowance itself reopens,…	number

Try itanswered in this tab

curl

curl "$SANDBOX/usage/limit-reset/work" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.usage.limitReset({
  "account": "work"
});

POST/usage/limit-reset/{account}/claimReopen this account's session window now

Spends one of the account's weekly resets to reopen its session window immediately. The weekly allowance is untouched and still binds. Answers with what the provider actually did: only `reset` changed anything, and it is the cue to send the refused turn again.

What you send

Field	Type	Where
`account`requiredWhich account	string	address

What comes back

Field	Type
`result`What the provider did	"reset" \| "already_used" \| "not_limited" \| "ineligible" … (6)
`nextAvailableAt`When another reset may be claimed,…	number
`detail`What went wrong, in words, for…	string

Try itanswered in this tab

curl

curl -X POST "$SANDBOX/usage/limit-reset/work/claim" \
  -H "x-intentic-control: $INTENTIC_TOKEN"

TypeScript

import { sandbox } from "@intentic/sandbox-client";

const result = await sandbox.usage.claimLimitReset({
  "account": "work"
});