---
title: Read the response envelope
category: query
summary: Understand coverage, temporal windows, usage, citations and the other fields wrapped around Manifests, so you know when an answer is safe to use.
order: 11
updated: 2026-10-07
next: manifest-anatomy-field-guide
related: freshness-and-available-through, troubleshoot-empty-windows-and-missing-manifests
reference: /docs/api, /agent-guide.md
---

A Manifest query returns evidence about itself: whether the answer is complete, the window it covered, what it cost, and how to cite it. Reading it is how you avoid telling your user "nothing happened" when the truth was "I could not tell".

## When to use this

Read the envelope **first** on every response, then the Manifests. It matters most for an empty, partial or surprising result.

## Smallest working call

Run a free count and read what comes back around it. Use `include_diagnostics` only to debug a surprising result; it adds large blocks:

```mcp
synorb-manifests
{"stream_ids": ["STREAM_ID"], "days": 3, "mode": "count"}
```

```bash
curl -sS -X POST https://api.synorb.com/manifests/query \
  -H "Authorization: Bearer $SYNORB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stream_ids": ["STREAM_ID"], "days": 3, "mode": "count"}'
```

## What you get back

### Did it run?

Success responses carry `ok`, `planned`, `executed` and `execution_status`. A request refused before execution (`executed: false`, with a reason such as `planning_failed`, `needs_scope` or `invalid_request`) has no Manifests and uses nothing. `planned: true`, `executed: true` with authoritative coverage is a **clean empty result**; anything else is not, and never authorizes a broader query.

### Can I trust it? `coverage`

`coverage` is the authoritative outcome: a status and a reason. A blocked, unresolved or authorization-failed scope is **not** an exact zero. A zero with `coverage.status: degraded` (for example `incomplete_evidence_not_a_gap`) is also not proof that nothing exists. Related proofs:

| Field | What it tells you |
| --- | --- |
| `coverage.status`, `coverage.reason` | Whether the result is complete, partial, or could not be proven, and why |
| `coverage.relevance_model` | Which engine ran: `tag_names` (exact graph), `query` (semantic), or both intersected |

A `positive_partial` page bills only the Manifests it returns. A `pending_scan` response returns no bodies and no charge. Follow its cursor. It is **not** evidence of no matches.

### What window did I get? `temporal`

`temporal` shows the window you asked for, the window that applied, and the ceiling. Read it before you say "last week". Fields to know:

- the effective start and end dates, which you should show your user,
- `availability_ceiling`, the newest date your plan can see. `GET /account` calls the same value `available_through`,
- `window_ceiling_age_seconds`, how old that ceiling is. It is **not** index staleness,
- `window_note`, present when a `wall_clock` window covers fewer hours than you asked for.

On MCP, `index_staleness_seconds` is the age of the newest item the serving index has seen. If it is absent, that does not mean zero.

`temporal` appears for relative windows (`days` and `lookback_hours`), not for an exact date range. If you asked for a future end date, `date_window_adjustment` says the server clamped it.

### What did it cost? `quota` and `usage`

`data.quota.manifests_billed_this_call` is the number billed by this call. `quota_used` and `quota_remaining` are the settled totals. If neither a usage envelope nor headers are present, do not infer a charge from the HTTP status.

### How do I cite it? `citation_contract`

Present in every successful query. `status: "required"` means preserve the returned citations and source URLs when you state a fact. `status: "none"` means no Manifests came back.

`executed_via_beacon` appears when a Beacon ran. Confirm its `topic_scope_mode` is the scope you intended.

### Read it in full: `response_profile`

The default profile is `full`. Each Manifest carries its Claims (`claim_text`, `claim_type`, `confidence` and evidence), the Signal, the Brief, the Record, the full `source` metadata, the Tags and the citations. Read all of that before you write. Never write from titles or one-liners.

Synorb does not recommend `slim`. It drops source metadata (`evidence_type`, `source_channel_display`, `content_quality`), `retrieval_context` and citation authority. Neither profile changes which Manifests the server returns or bills. A Manifest you already pulled is not billed again in the same billing period. The server omits `diagnostics`, `coverage_outcome`, `candidate_projection` and `manifest_index` by default. Pass `include_diagnostics: true` to get them when you must explain an absence.

## Failure modes

| Symptom | Cause | What to do |
| --- | --- | --- |
| You reported "nothing happened" but coverage was not authoritative | You read the empty list, not `coverage` | Check `coverage.status` first. If it is not authoritative, say you could not confirm. |
| An empty `manifests` after a recent date | The window is past `available_through` | Read `temporal`, and say the latest available date. |
| The response is huge | `include_diagnostics: true` on a big page | Turn diagnostics off and reduce `target_count`. |

## Make it good for your user

Turn evidence into honesty. "Covered through October 6 (your plan's latest available day); 41 matches" beats "here are the results".

## Next guide

[The Manifest anatomy field guide](/agent-guides/manifest-anatomy-field-guide): every part of a Manifest and the metadata worth using.