---
title: "Usage · intentic sandbox API"
description: "What has been spent, grouped. Every route in the usage group of the intentic sandbox API, with its input, its answer and a playground."
url: "https://intentic.dev/api/usage/"
---

Models and accounts

# Usage

What has been spent, grouped

**On this page (4 sections)**

- [What was spent, grouped](#usage-rollup)
- [Measure every account's plan limits again](#usage-refreshPlanLimits)
- [Whether this account's session window can be reopened now](#usage-limitReset)
- [Reopen this account's session window now](#usage-claimLimitReset)

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/rollup` What 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 it answered in this tab

curl

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

TypeScript

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

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

**POST`/usage/plan-limits/refresh` Measure 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 it answered in this tab

curl

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

TypeScript

```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` required Which 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 it answered in this tab

curl

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

TypeScript

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

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

**POST`/usage/limit-reset/{account}/claim` Reopen 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` required Which 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 it answered in this tab

curl

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

TypeScript

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

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

More in Models and accounts

[Previous ← Providers](https://intentic.dev/api/providers/)