---
title: Preflight with count, orient and plan
category: query
summary: Check scope, size and cost for free before you read anything. Use count, orient and plan to spend usage only on content you will show.
order: 10
updated: 2026-10-07
next: read-the-response-envelope
related: manifests-filter-cookbook, quotas-retries-and-pagination, troubleshoot-empty-windows-and-missing-manifests
reference: /agent-guide.md, /openapi.json
---

Reading Manifests costs usage, but **looking** at them does not. Three modes let you test the shape, size and cost of a query before you pay for a single body. Use them first. A careful agent does this. An expensive agent does not.

## When to use this

Use a preflight before any pull that is large, new, user-visible, or run on a schedule. Use it whenever you are unsure whether a scope returns anything, and always before a Beacon goes live.

| Mode | What it returns | Cost | Use it to |
| --- | --- | --- | --- |
| `count` | An exact `total_count` and breakdowns, with no bodies | Zero | Decide whether to read, and how much |
| `orient` | A free 7, 30 and 90 day snapshot | Zero | Get a feel for a topic's recent shape |
| `plan` | A signed zero-body preview and a `plan_token` | Zero | Lock a query's identity, or run balanced allocation |
| `default` | The Manifest bodies | Bills returned Manifests | Read content |

## Smallest working call

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

If the count is worth reading, ask for a modest page. This one bills only what it returns:

```mcp billed
synorb-manifests
{"stream_ids": ["STREAM_ID"], "days": 7, "target_count": 5}
```

### Plan, then execute

Over REST, plan a request and then replay it with the token. Planning validates and fingerprints the request without billing:

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

Then send the **identical** request plus the `plan_token` you received. Any other change invalidates it:

```bash billed
curl -sS -X POST https://api.synorb.com/manifests/exec \
  -H "Authorization: Bearer $SYNORB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stream_ids": ["STREAM_ID"], "days": 2, "mode": "default", "target_count": 5, "plan_token": "PLAN_TOKEN"}'
```

Over MCP the same pair is `mode: "plan"`, then a default call carrying the returned `plan_token`.

A plan is optional for an ordinary pull and required for balanced mixed-family research (`allocation_policy: "balanced"`).

## What you get back

A `count` response has an exact total and no bodies:

```json response
{
  "ok": true,
  "data": {
    "manifests": [],
    "pagination": {"total_count": 41, "count_basis": "published_snapshot"},
    "quota": {"manifests_billed_this_call": 0}
  }
}
```

A `plan` response has the token and the proof that nothing was billed:

```json response
{
  "plan_token": "synorb_plan_...",
  "request_fingerprint": "sha256:...",
  "quota_charged": false,
  "execute": "POST /manifests/exec with the identical request plus plan_token"
}
```

The exact count is exact for the published snapshot it names (`count_generation`). Items published after that snapshot appear on a later refresh, and they do not retroactively change the count.

### Reading the preflight

- **A positive count** under a few dozen: read it all, or the top slice by `significance`.
- **A large count:** narrow with a filter, tighten the window, or read the top `target_count` and say there is more.
- **Zero:** do not conclude "nothing happened". Check the window against `available_through`, and read the empty-window guide.
- **`orient`** is a sample. It cannot support a complete briefing, so use it to choose and `default` mode to answer.

### Size and speed

A scope of about 200 to 250 Streams fits in the REST default of 5,000 ms. Above that, split the Streams into shards of about 200, make one call per shard, merge by `manifest_id`, and sum counts only when the shards are disjoint. Over REST you can raise `timeout_ms` up to 15,000. MCP has a fixed interactive budget and no such field. The server refuses an explicit scope above 5,000 IDs. A call that runs out of time reports `absolute_request_deadline_expired` and returns no paid partial result.

### Staying in sync

For durable sync of newly delivered items, REST also offers `delivery_delta: true` with a signed `checkpoint`. It reads a **narrower** population than an ordinary query. A Manifest enters it only after the server routes it for delivery. An authoritative zero from delta means "nothing entered the delivery pipeline in this window". It never means "nothing matched". Most agents should use ordinary queries with an overlapping window, as the scheduling guide describes.

## Failure modes

| Symptom | Cause | What to do |
| --- | --- | --- |
| `409` on exec, zero usage | The body changed after planning, or the token was already used | Plan again with the full new request. |
| `409` on `/manifests/query` with a plan token | Tokens belong to `/manifests/exec` | Send the token to exec only. |
| `exact_count_unavailable` | The server cannot prove a total right now | Retry later, or read with `default`. Nothing was billed. |
| `index_proof_unavailable` with `retryable: true` | A transient consistency check | Re-POST the same body after a short delay. |
| `final_scope_authorization_failed` | The scope does not match what you may read | Fix the scope. Do not retry. |
| `absolute_request_deadline_expired` | The scope is too big for the time budget | Shard the scope. |
| A count and a later default pull differ slightly | New items landed between the two calls | Treat the count as a snapshot, not a promise. |

## Make it good for your user

Preflight is also how you talk to your user before spending anything. "There are 41 new items in your window, and 4 are high significance. I will read those four." That sentence comes from one free call. It tells your user you are careful with their allowance. The answer that follows then looks chosen and not dumped.

## Next guide

[Read the response envelope](/agent-resources/read-the-response-envelope): understand coverage, temporal windows, allowance and the other fields wrapped around the Manifests.