---
title: The Manifest filter cookbook
category: query
summary: Every filter on a Manifest query, how filters combine, and tested recipes that turn real questions into precise, cheap pulls.
order: 9
updated: 2026-10-07
next: preflight-count-orient-plan
related: resolve-tags-and-entities, source-channel-metadata-and-filters, preflight-count-orient-plan
reference: /docs/api, /docs/mcp, /openapi.json
---

`synorb-manifests` over MCP and `POST /manifests/query` over REST share one filter set. If you know the whole set and how the pieces combine, you can ask for exactly the content a question needs and nothing else.

## When to use this

Use it when you are turning a user's question into a pull. Start from the recipe closest to the question, then adjust.

## Smallest working call

Count what a question would return. It bills nothing:

```mcp
synorb-manifests
{"stream_ids": ["STREAM_ID"], "source_class": ["company_first_party"], "significance": "high", "days": 7, "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"], "source_class": ["company_first_party"], "significance": "high", "days": 7, "mode": "count"}'
```

The REST body is strict. An unknown field returns a `422`. The server does not ignore it. A typo cannot quietly broaden a query.

## What you get back

### How filters combine

- **Different filters narrow each other.** A Stream, plus a publisher class, plus a Tag, plus a date window returns only items that satisfy all of them.
- **Values inside one list are alternatives.** `stream_ids: [A, B]` returns items from A or B. `source_class: [x, y]` returns either class.
- **Tags have their own logic.** `tag_logic: "or"` (the default) matches any named Tag. `"and"` requires them all in the same Manifest.
- **Domains have theirs.** `cross_domain_logic` is `and` or `or`.
- **Omitting scope is broad on purpose.** If you leave out `stream_ids`, you query the visible catalog. The server rejects an explicit empty list at zero usage.

### The filters, by job

| Job | Filters |
| --- | --- |
| **Scope** | `stream_ids` (or `stream_id`), `home_domains`, `cross_domains` and `cross_domain_logic`, `source_channel_ids`, `source_channel_names` |
| **Time** | `published_date_from` and `published_date_to` (inclusive, `YYYY-MM-DD`), `days`, `lookback_hours`, `relative_to` (`available_through`, the default, or `wall_clock`) |
| **About** | `tag_names`, `tag_ids`, `tag_type`, `subtype`, `tag_logic`, `query` (semantic) |
| **By** (who published) | `source_class`, `evidence_type`, `media_format` |
| **Company and filings** | `ticker`, `isin`, `sec_ticker`, `sec_cik`, `sec_form_type`, `sec_form_variant`, `sec_item_code`, `sec_item_subsection`, `sec_exhibit_type` |
| **Weight** | `significance`: `high`, `medium` or `low` |
| **Exclude** (best effort) | `exclude_tag_names`, `exclude_tag_ids`, `exclude_query_terms`, `exclude_source_channel_ids`, `exclude_home_domains` |
| **Shape the output** | `compact`, `verbosity`, `markdown_version`, `response_profile`, `include_diagnostics` |
| **Page and size** | `page` (or `page_num`), `page_size` (up to 200), `target_count` (up to 200) |
| **Run mode** | `mode`, `plan_token`, `beacon_id`, `broaden_sources`, `timeout_ms` (REST only) |

Notes on the less obvious ones:

- `days` and an explicit date range are mutually exclusive. `lookback_hours` and `days` anchor to your plan's `available_through`.
- `ticker` is a broad company-identity filter: everything about that company. `sec_ticker` is narrower: only SEC filing Manifests carrying that ticker. They are not interchangeable.
- SEC filters are exact. `sec_form_type: ["8-K"]` never changes to a near form. An unresolved SEC scope reads as zero coverage. It does not widen.
- `exclude_*` filters are best effort. They drop matches at lookup time but are not a hard guarantee.
- On MCP, `session_id`, a stable client UUID you choose, caches returned Manifests for 30 minutes, so follow-up questions in the same conversation cost no extra usage. REST accepts the field, but repeat pulls are billed as normal.
- `significance` ranks how consequential an item is. Use it to cut noise, and still read the items you keep.

### Recipes

**Official announcements from one company, this week.**

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

**What the Fed itself said, versus everything said about the Fed.** The first narrows to central-bank authorship. Drop `source_class` for the second.

```mcp
synorb-manifests
{"tag_names": ["Federal Reserve"], "source_class": ["central_bank"], "home_domains": ["economics-business-work"], "days": 30, "mode": "count"}
```

**Exact SEC filings.** Name the form. Never substitute a similar one. A count of zero with `coverage.status: degraded` is not proof that no filing exists. Read `coverage` before you tell your user.

```mcp
synorb-manifests
{"ticker": ["NVDA"], "sec_form_type": ["8-K"], "days": 30, "mode": "count"}
```

**Two entities mentioned together.**

```mcp
synorb-manifests
{"stream_ids": ["STREAM_ID"], "tag_names": ["OpenAI", "Microsoft"], "tag_logic": "and", "days": 30, "mode": "count"}
```

**Only the items that matter most, minus a noisy term.** An `exclude_*` filter is best effort. Counts that use one report `coverage.reason: exact_scope_not_proven`.

```mcp
synorb-manifests
{"stream_ids": ["STREAM_ID"], "significance": "high", "exclude_query_terms": ["sponsored"], "days": 14, "mode": "count"}
```

**Podcast episodes about a topic.**

```mcp
synorb-manifests
{"home_domains": ["economics-business-work"], "media_format": "audio", "tag_names": ["Monetary Policy"], "days": 14, "mode": "count"}
```

**An idea with no single Tag** (semantic). Pair it with a scope. The server refuses a bare broad word.

```mcp
synorb-manifests
{"stream_ids": ["STREAM_ID"], "query": "supply chain resilience", "days": 14, "mode": "count"}
```

**An exact historical range.**

```mcp
synorb-manifests
{"stream_ids": ["STREAM_ID"], "published_date_from": "2026-09-01", "published_date_to": "2026-09-30", "mode": "count"}
```

For a recipe you like, change `"mode": "count"` to the default (or remove it) when you are ready to read the content. Counting first is free. The default mode bills the Manifests it returns.

## Failure modes

| Symptom | Cause | What to do |
| --- | --- | --- |
| `422` with an unknown field | The REST body is strict | Remove or rename the field. |
| Zero results from two filters that seem right | Filters narrow each other, or `tag_logic: "and"` is too strict | Count each filter alone to find the one that empties it. |
| `context_unigram_scope_too_broad` | A bare one-word `query` with no resolved Tag | Add `tag_names`, or make the phrase specific. |
| `tag_names_unresolved` | A name is not a canonical Tag | Look it up with the Tags guide. |
| Results broader than expected | You omitted `stream_ids` | Pass explicit IDs. |
| `required_surfaces` rejected | It needs balanced allocation and a plan first | Leave it out unless you truly need balanced mixed-family research. |
| `final_scope_authorization_failed` after you add an `exclude_*` filter | The scope without the exclusion already matches nothing, so the exclusion cannot be applied | Count without the exclusion first. Widen the window or the scope until it matches, then add the exclusion. |
| Two filters give different counts for one phrase | `tag_names` is an exact census, and `query` is semantic | Use the one that matches the question. Both together intersect. |

## Make it good for your user

Show your user how you narrowed the pull. "I looked at NVIDIA's own announcements from the last seven days and kept only the high-significance ones: 4 items." That sentence states your filters in plain words. A question can have an obvious wider reading, for example everyone's coverage and not only the company's own. If so, say which reading you chose and offer the other.

## Next guide

[Preflight with count, orient and plan](/agent-resources/preflight-count-orient-plan): check scope, size and cost for free before you read anything.