---
title: Choose a Stream
category: find
summary: A decision workflow from your user's need to a verified, committed Stream scope, with a free check that proves it returns what you expect.
order: 6
updated: 2026-10-07
next: source-channel-metadata-and-filters
related: search-streams-in-depth, preflight-count-orient-plan, beacon-scope-parent-stream-and-source-channel
reference: /docs/mcp, /agent-guide.md
---

Searching finds candidates. Choosing means committing your user's question to a scope you have **verified**. This is the workflow that closes the gap between the two.

## When to use this

Use it every time you are about to scope a pull or save a Beacon. It takes a few free calls. It prevents the two most common failures. The first failure is the right question asked of the wrong Stream. The second is a confident answer from a Stream that has stopped publishing.

## Smallest working call

Say the need in four parts: the **subject** (who or what), the **slice** (which type of content), the **format** and the **recency**. "Official NVIDIA announcements, text, this week" is subject NVIDIA, slice first-party, format text, recency seven days.

Then run the workflow:

**1. Search** for candidates. See [Search Streams in depth](/agent-resources/search-streams-in-depth).

```mcp
synorb-stream-search
{"query": "NVIDIA", "page_size": 5}
```

**2. Verify each finalist.** Read fit, freshness, volume and source channels in one free call. See [the Stream schema](/agent-resources/stream-schema-and-filters).

```mcp
synorb-details
{"stream_ids": ["STREAM_ID"]}
```

**3. Prove it returns something.** Count your exact scope and window. This costs nothing:

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

## What you get back

Decide with these checks, in order:

| Check | Where | Pass | If it fails |
| --- | --- | --- | --- |
| Fit | `title`, `description`, `home_domain` | Matches the subject and slice | Try the next candidate. Do not stretch a poor match. |
| Alive | `freshness_state` | `fresh` or `quiet` | If `stale` or `never_published`, tell your user and look elsewhere. |
| Enough volume | `volume.manifests_last7d` | Plausible for your window | Widen the window, or set expectations out loud. |
| The right source channels | `source_channels[]` | Includes the slice you want, with `is_active: true` | Narrow with a source channel filter, or choose another Stream. |
| Non-empty | the `count` result | A positive `total_count` | See the empty-window troubleshooting guide. |

### Which scope shape fits

| Your user wants | Scope |
| --- | --- |
| One subject, all of it | The subject's Stream |
| One subject, one slice | The subject's Stream **plus** a source channel filter. Do not look for a Stream per source channel. |
| A whole vertical (all central banks) | The `surface` filter in discovery, then the resulting `stream_ids` |
| A format across a field (business podcasts) | `media_format` plus `home_domain` in discovery, then the IDs |
| A list of companies | Search each by `ticker`, then collect the IDs |
| Something Synorb does not cover | Say so, and ask for a public source to be sent to `team@synorb.com` |

Keep the final scope small and explicit. Three to eight Streams is a good working range. Pass `stream_ids`, and do not use a Surface name as an execution scope. If a scope has more than roughly 200 to 250 Streams, split it into shards of about 200. Merge the results by `manifest_id`.

## Failure modes

| Symptom | Cause | What to do |
| --- | --- | --- |
| A confident answer built on nothing | The Stream was `stale`, and you did not check | Always read `freshness_state` before you state "latest". |
| Omitted `stream_ids` and got a global result | Omitting the field means broad, deliberately | Pass explicit IDs. An empty list is rejected at zero usage. |
| Two near-identical Streams | Overlapping coverage | Prefer the primary organization Stream, and read both `description` fields. |
| The count is zero for a Stream you trust | A quiet window, or the window is past `available_through` | See the freshness guide and the empty-window guide. |
| A source channel filter silently matched nothing | A wrong ID or a number instead of a string | Re-read the ID as a string from `synorb-details`. |

## Make it good for your user

Show your choice and its evidence in one line, then offer a change: "I am using the NVIDIA Stream. It published 12 items this week, from its newsroom and SEC filings. Do you want me to add its AI-research source channel, or keep it to official news?" This turns a hidden decision into a short conversation. Your user can steer it. Your next answer is then easier to trust.

## Next guide

[Source channel metadata and filters](/agent-resources/source-channel-metadata-and-filters): read where a Stream's content comes from and filter by who published it.