---
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 commits to a **verified** scope.

## When to use this

Use it to scope a pull or save a Beacon. If your user names a saved Beacon, pull by `beacon_id` with an explicit window; skip the search. Free calls prevent two failures: the right question asked of the wrong Stream, and 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-guides/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-guides/stream-schema-and-filters).

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

```bash
curl -sS https://api.synorb.com/streams/STREAM_ID   -H "Authorization: Bearer $SYNORB_KEY"
```

Over REST the same facts are flat fields under `data`: `title`, `freshness_state`, `manifests_last7d` and `source_channels[]`. MCP groups the counts under `volume`. The table below uses the MCP names.

**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` (REST: `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` |
| 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. Pass `stream_ids`, and do not use a Surface name as an execution scope. Split a scope above about 200 Streams into shards, and merge by `manifest_id`.

## Failure modes

| Symptom | Cause | What to do |
| --- | --- | --- |
| A confident answer built on nothing | The Stream was `stale` | 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. |
| 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. |

## 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. Do you want me to add its AI-research source channel?"

## Next guide

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