---
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.

## When to use this

Use a preflight before any pull that is large, new, user-visible, or scheduled. Use it when you are unsure 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. Balanced mixed-family research (`allocation_policy: "balanced"`) requires one.

## 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 a `plan_token`, a `request_fingerprint` and `quota_charged: false`.

The count is exact for the published snapshot it names (`count_generation`). Later items do not change it.

### 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. 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, and merge by `manifest_id`. A call that runs out of time reports `absolute_request_deadline_expired` and returns no paid partial result.

For durable sync of new items, REST also has `delivery_delta: true`. It reads a narrower population than an ordinary query. Most agents should use ordinary queries with an overlapping window. See [Read only what is new from a Beacon](/agent-guides/read-only-whats-new-from-a-beacon).

## 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. |
| `index_proof_unavailable` with `retryable: true` | A transient 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. |

## Make it good for your user

Preflight lets 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.

## Next guide

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