---
title: "report.ai-usage-me-result@2 · OpenVibe.Services"
canonical: "https://openvibe.services/docs/contracts/report.ai-usage-me-result"
updated: null
---

# report.ai-usage-me-result@2 · OpenVibe.Services

HTML: [report.ai-usage-me-result@2 · OpenVibe.Services](https://openvibe.services/docs/contracts/report.ai-usage-me-result)

# ReportAiUsageMeResultV2 `report.ai-usage-me-result@2`

Generated at 2026-11-13 06:25:48 UTC from [`openvibe-contracts v0.419.0`](https://github.com/OpenVibers/OpenVibe.Contracts/tree/v0.419.0) and [`openvibe-sdk v0.161.0`](https://github.com/OpenVibers/OpenVibe.SDK/tree/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`](/docs/contracts/report.ai-usage-me-result.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. | - `one of "day", "week", "month", "provider", "model", "surface", "paid_by"` |
| `rows` | array of object | yes | One row per bucket, sorted by key. Empty when the window has no calls. | - `items: no other fields` |
| `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. | - `maxLength 200` |
| `rows[].calls` | integer | yes |  | - `minimum 0` |
| `rows[].input_tokens` | integer | yes | The uncached input tokens. | - `minimum 0` |
| `rows[].output_tokens` | integer | yes |  | - `minimum 0` |
| `rows[].cached_tokens` | integer | yes | The input tokens read from a provider cache. | - `minimum 0` |
| `rows[].cache_write_tokens` | integer | yes | The input tokens written to a provider cache. | - `minimum 0` |
| `rows[].cost_usd` | number | yes | What the tokens cost at list prices. | - `minimum 0` |
| `rows[].fee_usd` | number | yes |  | - `minimum 0` |
| `rows[].charged_usd` | number | yes |  | - `minimum 0` |
| `rows[].saved_usd` | number | yes | What the cache saved against the plain input price. | - `minimum 0` |
| `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. | - `no other fields` |
| `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. | - `one of "raw", "rollups", "raw+rollups"` |

## 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 }] }
~~~~