ReportAiUsageMeResultV2 report.ai-usage-me-result@2
Generated at from
openvibe-contracts v0.419.0 and
openvibe-sdk v0.161.0.
- Version
- 2.0.0
- Owner
- report
- Visibility
- public
- Status
- active
- Compatibility
- backward
- Schema
https://openvibe.network/contracts/report/ai-usage-me-result.v2.json
report.ai-usage-me-result@2: the AI usage of one person (plan L41 R1). GET /api/v1/me/ai/usage answers for the person their session names and nobody else: the rows of one group (day, week, month, provider, model, surface or paid_by), the totals, what each way of paying cost, two or three plain lines worked out from the numbers, and the source that answered (raw records, the roll-ups, or both). v2 replaces v1's `usage` array and its `input`/`output`/`reasoning`/`cache_read`/`cache_write`/`list_cost_usd`/`cache_saved_usd` names with `rows` and the names the route answers: `input_tokens`, `output_tokens`, `cached_tokens`, `cache_write_tokens`, `cost_usd` and `saved_usd`. The route answers 401 signed out; the subject is the session's, never the query.
Fields
| Field | Type | Required | Description | Constraints |
|---|---|---|---|---|
group | enum | yes | The bucket the rows are grouped by; a person may ask for any of the seven. |
|
rows | array of object | yes | One row per bucket, sorted by key. Empty when the window has no calls. |
|
rows[].key | string | yes | The bucket's key: a day (YYYY-MM-DD), a week (its Monday), a month (YYYY-MM), a provider, a model, a surface or a payer; 'unknown' when the record has no such value. |
|
rows[].calls | integer | yes |
| |
rows[].input_tokens | integer | yes | The uncached input tokens. |
|
rows[].output_tokens | integer | yes |
| |
rows[].cached_tokens | integer | yes | The input tokens read from a provider cache. |
|
rows[].cache_write_tokens | integer | yes | The input tokens written to a provider cache. |
|
rows[].cost_usd | number | yes | What the tokens cost at list prices. |
|
rows[].fee_usd | number | yes |
| |
rows[].charged_usd | number | yes |
| |
rows[].saved_usd | number | yes | What the cache saved against the plain input price. |
|
totals | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | yes | ||
by_paid_by | object | yes | What each way of paying cost over the same window; a payer with no calls is absent. |
|
by_paid_by.own_key | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | |||
by_paid_by.openvibe_key | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | |||
by_paid_by.plan | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | |||
by_paid_by.own_machine | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | |||
by_paid_by.free_tier | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | |||
by_paid_by.network_allowance | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | |||
by_paid_by.org_key | https://openvibe.network/contracts/report/ai-usage-me-result.v2.json#/$defs/measure | |||
insights | array of string | yes | Two or three plain lines worked out from the numbers, one when the window has no calls; never an AI call. | |
source | enum | yes | Which tables answered: raw records inside the 90-day retention, the roll-ups beyond it, or both. |
|
Examples
From the contract's own test fixtures: valid ones validate, rejected ones must fail.
Valid: empty
{
"group": "day",
"rows": [],
"totals": {
"calls": 0,
"input_tokens": 0,
"output_tokens": 0,
"cached_tokens": 0,
"cache_write_tokens": 0,
"cost_usd": 0,
"fee_usd": 0,
"charged_usd": 0,
"saved_usd": 0
},
"by_paid_by": {},
"insights": [
"No AI calls in this window."
],
"source": "rollups"
}Valid: mine
{
"group": "paid_by",
"rows": [
{
"key": "openvibe_key",
"calls": 1,
"input_tokens": 1000,
"output_tokens": 500,
"cached_tokens": 0,
"cache_write_tokens": 100,
"cost_usd": 0.05,
"fee_usd": 0.01,
"charged_usd": 0.06,
"saved_usd": 0
},
{
"key": "own_key",
"calls": 2,
"input_tokens": 250,
"output_tokens": 90,
"cached_tokens": 800,
"cache_write_tokens": 0,
"cost_usd": 0.0031,
"fee_usd": 0,
"charged_usd": 0,
"saved_usd": 0.0017
}
],
"totals": {
"calls": 3,
"input_tokens": 1250,
"output_tokens": 590,
"cached_tokens": 800,
"cache_write_tokens": 100,
"cost_usd": 0.0531,
"fee_usd": 0.01,
"charged_usd": 0.06,
"saved_usd": 0.0017
},
"by_paid_by": {
"openvibe_key": {
"calls": 1,
"input_tokens": 1000,
"output_tokens": 500,
"cached_tokens": 0,
"cache_write_tokens": 100,
"cost_usd": 0.05,
"fee_usd": 0.01,
"charged_usd": 0.06,
"saved_usd": 0
},
"own_key": {
"calls": 2,
"input_tokens": 250,
"output_tokens": 90,
"cached_tokens": 800,
"cache_write_tokens": 0,
"cost_usd": 0.0031,
"fee_usd": 0,
"charged_usd": 0,
"saved_usd": 0.0017
}
},
"insights": [
"67% of your calls ran on your own keys, so no fee on those.",
"The cache saved you less than $0.01 this month.",
"Your calls cost $0.06, including $0.01 in fees."
],
"source": "raw"
}Rejected: carries-a-person
{
"group": "day",
"rows": [],
"totals": {
"calls": 0,
"input_tokens": 0,
"output_tokens": 0,
"cached_tokens": 0,
"cache_write_tokens": 0,
"cost_usd": 0,
"fee_usd": 0,
"charged_usd": 0,
"saved_usd": 0
},
"by_paid_by": {},
"insights": [
"No AI calls in this window."
],
"source": "raw",
"subject": "usr_01JAB2C3D4E5F6G7H8J9K0MNPQ"
}Rejected: unknown-payer
{
"group": "day",
"rows": [],
"totals": {
"calls": 0,
"input_tokens": 0,
"output_tokens": 0,
"cached_tokens": 0,
"cache_write_tokens": 0,
"cost_usd": 0,
"fee_usd": 0,
"charged_usd": 0,
"saved_usd": 0
},
"by_paid_by": {
"someone_else": {
"calls": 0,
"input_tokens": 0,
"output_tokens": 0,
"cached_tokens": 0,
"cache_write_tokens": 0,
"cost_usd": 0,
"fee_usd": 0,
"charged_usd": 0,
"saved_usd": 0
}
},
"insights": [
"No AI calls in this window."
],
"source": "raw"
}Validate
const contracts = require('openvibe-contracts');
contracts.validate('report.ai-usage-me-result@2', value); // { valid, errors: [{ path, message }] }