---
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 more than Manifests. It returns evidence about the query itself: whether the answer is complete, what window it covered, what it cost, and how to cite it. Reading that evidence is how you avoid telling your user "nothing happened" when the truth was "I could not tell".

## When to use this

Use it on every response before you act on it. Read the envelope **first**, then the Manifests. It is most important when a result is empty, partial, or surprising.

## Smallest working call

Run a free count and look at what comes back around it. Turn on `include_diagnostics` only when you are debugging a surprising result, because 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", "response_profile": "slim"}'
```

## 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`) contains no Manifests and uses nothing. `planned: true`, `executed: true` with authoritative coverage is a **clean empty result**. Anything else is not an empty result, and it never authorizes you to broaden the 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 |
| `candidate_projection` | The pre-execution candidate set, and a `truncation_reason` if the scope could not be proven |
| `final_scope_authorization` | Proof the executed scope matches what you may read. If `authorized` is false, correct the scope and re-plan |
| `did_you_mean` | Canonical suggestions for a Tag or source channel name that did not resolve |
| `result_fingerprint` | A stable identity for this page, for cache and audit comparisons. It is not a freshness timestamp |

A `positive_partial` page bills only the Manifests it returns. A `pending_scan` response returns no bodies and no charge, but you must follow its cursor, and 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. The older name `lag` means the same thing and is **not** index staleness.

On MCP, the separate top-level `index_staleness_seconds` is the age of the newest published item the serving index has seen. The server omits it when it cannot measure it. If it is absent, that does not mean zero.

`temporal` appears for relative windows (`days` and `lookback_hours`). An exact date range does not get one. If you asked for a future end date, `date_window_adjustment` says the server clamped it to the latest delivered date.

### 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. Some responses, including certain Beacon and `429` ones, carry no usage headers. 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.

### Did a Beacon run? `executed_via_beacon`

A Beacon run reports `beacon_id`, `name` and `topic_scope_mode` (`saved`, `caller_narrowed` or `caller_override`). Read it to confirm the scope you intended is the scope that ran.

### Keep it small: `response_profile`

`full` is the default. `slim` drops the operator-only blocks (`manifest_index`, `candidate_projection`, and others) and reduces each Manifest's `source` to `source_name`, `source_url`, `media_format` and `source_class`. It drops `evidence_type`, `source_channel_display`, `content_quality`, `source_reachability` and the other source fields. It never changes which Manifests the server returns or bills. Under either profile, the server omits `diagnostics` and `coverage_outcome` by default. Pass `include_diagnostics: true` to get them back 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. |
| `evidence_type`, `source_channel_display` or `content_quality` is missing | You chose `slim` | Use the default profile if you need them. |
| The response is huge | `include_diagnostics: true`, or the full profile on a big page | Turn diagnostics off, use `slim`, and reduce `target_count`. |
| `executed: false` | The request was refused | Read the reason. Nothing was billed. Fix the scope or fields, then retry. |
| A used count differs from your tally | Dedup counted a repeated Manifest once | Trust `manifests_billed_this_call`. |

## Make it good for your user

Turn evidence into honesty. "Covered through October 6 (your plan's latest available day); 41 matches" is better than "here are the results". And "I could not confirm the last day, so treat that as unknown" is better than a confident gap. Users accept limits when you tell them about the limits. Users do not accept a wrong answer that you state with confidence.

## Next guide

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