> ## Documentation Index
> Fetch the complete documentation index at: https://docs.niadra.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Context use
> Measurement per agent and per vendor: use, repetition, contradiction and handoff without reading.
A memory that is delivered and never used is worth nothing. Niadra measures whether each agent used the context it received, per agent, per vendor and per channel. Only the memory can do this: it holds both sides of the account, the pack that was delivered and the conversation that came next. The measurement looks at what the agent did with the context. It never grades a vendor, never suggests a prompt and never decides anything.
## The four signals
| Signal | What it means | How it is detected | What does not count |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Use** | The agent cited or relied on an item it received: the missed visit, the \$40 credit, the earlier promise | Deterministic match between the items of the delivery manifest and the agent turns (dates, amounts and ids normalized), plus the actions recorded in the session | An item that was delivered and was irrelevant to the task counts as not used, with no penalty |
| **Repetition** | After the delivery, the agent asked for data it already had at that verification level: name, document number, order number, reason for contact | The questions extracted from the conversation, matched against the items and categories of the manifest | A verification question your policy requires; an explicit confirmation of a delivered value when the source is marked "confirms before acting"; a question about an item the policy withheld |
| **Contradiction** | The agent said something a delivered fact or action disproves: "the credit is still under review" with the 2:06 pm action in the pack | The agent's claims reconciled against the facts and actions delivered | A divergence with a fact that was not in the pack. That is a selection gap, measured apart, never attributed to the agent |
| **Handoff without reading** | The conversation went to a human or another agent, and the receiver never asked for context | A `handoff` event with no receipt from the target source for that conversation within 10 minutes | A handoff to a source that is not integrated. It shows up in coverage instead |
What counts as delivered: the pack, the `live` turns, the `delta` and the items returned by history navigation, each with its delivery time, as recorded in the receipts. Only a question asked after the delivery is a repetition. A cited item counts as used only when it is pertinent to the turn, so reciting the whole pack does not inflate the number. For internal agents, use is measured by the recorded action, and repetition is reported as not measured.
## Coverage comes first
Two counters sit next to the signals:
* **Sessions without context**: the source integrated `track` but never called `context()`.
* **Late context**: the context arrived after the agent's first answer.
The SDK stamps `context_injected_at` and `first_agent_turn_at` on the conversation for you when you use `conversation()` and its `agent()` turn. Without coverage there is nothing to measure, and the number appears as **not measured**, never as zero. In the API a rate with nothing to measure is `null`.
Voice has one more rule. An agent turn whose speech recognition confidence is below the threshold produces no question and no claim. A first transcript pass without the agent's text is marked not measured, with the reason `partial_transcript`, and the second pass measures again. The text your agent's model generated, captured by the SDK, is worth more than the transcript.
## How it runs
The measurement runs on the same path as extraction, with no extra language model call. The questions and claims of the agent come out of the single extraction call that already exists; matching them against the manifest is deterministic. Results are ready together with the derived memory, in under a minute after the session ends. A second phase runs 10 minutes after the end to check whether the receiver of a handoff read the context. Everything is recomputed when the extractor changes version: the measurement is derived data, never the source of truth.
## Read the numbers
[`GET /v1/context-use`](/en/api/context-use) groups by any of `day`, `source_id` (the default), `vendor`, `channel`, `view` and `experiment_group`, repeating `group_by`, and filters by `since` and `until` (dates), `source_id`, `channel`, `view` and `experiment_group`. It takes a Console person with the `analysis` or `vendor` role, or a key with the `admin` scope.
```bash cURL theme={null}
curl "https://acme-prod.us-east-1.api.niadra.com/v1/context-use?group_by=vendor&group_by=channel&since=2026-09-01&until=2026-09-22" \
-H "Authorization: Bearer $NIADRA_TOKEN"
```
```python Python theme={null}
import os
import httpx
response = httpx.get(
"https://acme-prod.us-east-1.api.niadra.com/v1/context-use",
params={"group_by": ["vendor", "channel"], "since": "2026-09-01", "until": "2026-09-22"},
headers={"Authorization": f"Bearer {os.environ['NIADRA_TOKEN']}"},
)
for bucket in response.json()["buckets"]:
rate = bucket["usage_rate"]
print(bucket["vendor"], bucket["channel"], rate and (rate["value"], rate["low"], rate["high"]))
```
```typescript TypeScript theme={null}
const url = new URL("https://acme-prod.us-east-1.api.niadra.com/v1/context-use");
for (const g of ["vendor", "channel"]) url.searchParams.append("group_by", g);
url.searchParams.set("since", "2026-09-01");
url.searchParams.set("until", "2026-09-22");
const response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.NIADRA_TOKEN}` } });
const { buckets } = await response.json();
```
Each bucket counts `sessions`, `deliveries`, `deliveries_used`, `questions`, `repeated`, `contradicted`, `transfers`, `transfers_unread`, `recontacts`, `late_deliveries`, `no_context` (sessions without any context read), `not_measured` and `selection_misses` (contradictions of items the pack did not carry, which are never the agent's). The rates `usage_rate`, `repetition_rate`, `transfer_unread_rate` and `recontact_rate` come with `value`, the bounds `low` and `high` of a 95% Wilson interval and the sample `n`, and are `null` when nothing could be measured, never zero. To see why a number moved, open one conversation with [Context use of a conversation](/en/api/context-use-conversation): one entry per delivery, with the items used, the repeated questions, the contradictions, whether it came late and the manifest it was measured against.
A person with the `vendor` role only sees the sources named in their role binding, so one vendor never sees the numbers of another. Niadra never compares vendors in public. What you do with the numbers is up to you.
## Control group and 72-hour recontact
The measurement explains; recontact proves. A recontact is a session the customer starts within 72 hours of the end of another, on the same profile, in the same normalized category (or any category, for the overall rate). Outbound contact from your company does not count.
To measure the effect of the memory, your space can run an experiment: a stable fraction of customers, drawn by an HMAC of their oldest handle, receives the memory, and the rest form the control group. The same customer stays in the same group on every channel and vendor. For the control group, `context()` returns an empty pack with `path: "holdout"` and navigation returns empty, while the memory keeps being built so the comparison holds. The SDK treats `holdout` as an empty pack, never as an error. A shadow manifest records what would have been delivered, which is how repetition is counted for the control group. Sessions with an overdue company promise, a regulated category or a source marked critical leave both groups and receive the memory normally. Control-group sessions are not billed.
## Sampled review
Your team checks the measurement by sample. [`GET /v1/review/queue`](/en/api/review-queue) hands out up to 50 samples at a time, with the facts the memory extracted, the signals the measurement found and the new patterns, shown with the mask of the reviewer's role. A reviewer records a verdict per item with [`POST /v1/review/{sample_id}/verdicts`](/en/api/review-verdicts): the `target` (`fact`, `signal` or `trait`), its id and the verdict. Verdicts are the one governance write that only a person makes: it takes a Console person with the `review` role, never a source key. [`GET /v1/review/agreement`](/en/api/review-agreement) shows how much reviewers and the system agree over the last `days` (90 by default), which is the number that tells you whether to trust the measurement. A verdict never changes the memory by itself: a wrong fact leaves through [a correction](/en/api/feedback), a wrong pattern through [a retraction](/en/api/trait-retract).
## Usage
What your space consumes comes from [`GET /v1/usage`](/en/api/usage), for a `since` and `until` window, by `hour` or `day`, optionally for some `metric` values. With `group_by=source`, each row names the source, so you see which agent and vendor drove the conversations and tasks. It takes the `analysis` role or an `admin` key. The billed totals of the whole tenant are in the [control API](/en/api/control/usage). Control-group sessions are not billed.
## Privacy
The measurement reads what the cell already holds, and its result is about the agent, never about the data subject. Human attendants are aggregated by source, queue or team by default, never by the id of the person who answered; detail per person is off unless you configure it with a recorded legal basis. Erasing a profile removes its measurement rows through the same lineage.
## Next steps
the delivery record every signal points to.
get notified when a repetition rate crosses your threshold.
the aggregate endpoint in detail.
capture turns so the measurement has the agent's text.