---
title: Run and edit a Beacon
category: beacons
summary: Execute a saved Beacon with a lookback or exact dates, change it in place, and archive or restore it safely.
order: 19
updated: 2026-10-09
next: beacon-scope-parent-stream-and-source-channel
related: present-manifests-to-your-users, freshness-and-available-through
reference: /docs/api, /openapi.json
---

A saved Beacon holds scope. It does **not** hold a date window that runs by itself. Every run must send its own window. Make every change to the same Beacon with `synorb-update-beacon` or `PATCH`. Never archive and recreate.

## When to use this

Use this guide once you have a `beacon_id` (from `synorb-save-beacon` or `synorb-beacons`) and need to pull from it, adjust it after your user gives feedback, or retire it.

## Smallest working call

Run the Beacon over the last 24 hours. Over MCP:

```mcp billed
synorb-manifests
{"beacon_id": "BEACON_ID", "lookback_hours": 24}
```

Over REST, `POST /manifests/query` accepts `beacon_id` directly:

```bash billed
curl -sS -X POST https://api.synorb.com/manifests/query \
  -H "Authorization: Bearer $SYNORB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"beacon_id": "BEACON_ID", "lookback_hours": 24}'
```

The older path, `GET /streams/{stream_id}/manifests?beacon_id=...`, returns only that one Stream, which must be in the Beacon. There, `lookback_hours` counts back from the wall clock, not from `available_through`. Prefer `POST /manifests/query`.

### Choose the window exactly

Pick one style per run:

| You want | Send | Notes |
| --- | --- | --- |
| The recent past | `lookback_hours: 48` | Rounded up to whole publication days and anchored to `available_through`. `lookback_hours: 24` is one date, the latest available day. |
| A number of days | `days: 7` | A rolling window of available days, ending at `available_through`. |
| An exact range | `published_date_from` and `published_date_to`, both `YYYY-MM-DD` | Inclusive. Measured against each item's publication date, never its crawl time. |

"Last week" means a rolling seven available days, not the previous calendar week. If `available_through` is 2026-10-06, that is 2026-09-30 through 2026-10-06. **Show your user the effective inclusive dates** in your answer.

If the end date is in the future, Synorb sets it to the latest delivered date. The response reports the change in `date_window_adjustment`. Read that field. It shows you that "today" was not yet available.

```mcp billed
synorb-manifests
{"beacon_id": "BEACON_ID", "published_date_from": "2026-09-30", "published_date_to": "2026-10-06"}
```

## What you get back

Manifests arrive in `data.manifests[]`. Alongside them come `data.presentation_items[]` (one per Manifest, matched by `manifest_id`) and a `data.render` hint. The reading guides explain how to use both. The usage receipt is what to check for cost:

```json response
{
  "data": {
    "manifests": [{"manifest_id": "...", "signal": {}, "brief": {}}],
    "presentation_items": [{"manifest_id": "...", "title": "...", "source_url": "https://..."}],
    "render": {"suggested_format": "briefing", "max_items": 5},
    "quota": {"manifests_billed_this_call": 1}
  }
}
```

### Edit in place

Edit the existing Beacon. Do not archive it and make a new one. Over MCP, the edit takes three steps.

1. Read the Beacon. The reply holds its full settings and its `revision`:

```mcp
synorb-beacons
{"beacon_id": "BEACON_ID"}
```

2. Ask for a dry run. This is the default. The reply shows each change as `before` and `after`. It writes nothing:

```mcp
synorb-update-beacon
{"beacon_id": "BEACON_ID", "expected_revision": 3, "default_date_window": {"lookback_hours": 48}, "name": "Daily AI lab updates"}
```

3. Show the diff to your user. After your user says yes, send the same call with `dry_run` set to false. Skip the yes for a change to `default_date_window` alone when your user asked for recurring updates. Tell your user after you make it:

```mcp
synorb-update-beacon
{"beacon_id": "BEACON_ID", "expected_revision": 3, "default_date_window": {"lookback_hours": 48}, "name": "Daily AI lab updates", "dry_run": false}
```

The reply gives `previous_revision` and `new_revision`. You can change these fields: `name`, `description`, `tags`, `default_date_window`, `status` (`active` or `archived`), `stream_ids`, `source_channel_ids`, `topic_filters` and `manifest_config_patch`.

Follow these rules:

- `expected_revision` is required. If someone changed the Beacon after you read it, the call fails with `revision_mismatch` and the current revision. Read the Beacon again and rebuild the change.
- `stream_ids`, `source_channel_ids` and `topic_filters` replace the saved list. Keep the entries you still want.
- `manifest_config_patch` merges by key. A listed key is replaced. A key set to `null` is removed. Other keys stay.
- A change that widens scope fails with `scope_widening_refused`. Widening means adding a Stream or a source channel, or removing a topic filter. Ask your user. If your user agrees, add `allow_widening: true`.
- A starter Beacon keeps its `surface_ids` and `starter` keys. An edit to them fails with `protected_starter_field`.
- Setting `status` to `active` on an archived Beacon takes a plan slot. If your account is at its Beacon limit, the call fails with `beacon_limit_exceeded`. Archive a Beacon you no longer need first.

Over REST, `PATCH` does the same work with fewer checks. It replaces each field you send, including the whole `manifest_config`, and leaves other fields alone. Add `expected_revision` to get the same revision check. A stale revision returns HTTP 409.

```bash
curl -sS -X PATCH https://api.synorb.com/v3/beacons/BEACON_ID \
  -H "Authorization: Bearer $SYNORB_KEY" \
  -H "Content-Type: application/json" \
  -d '{"expected_revision": 3, "default_date_window": {"lookback_hours": 48}}'
```

Then call `GET /v3/beacons/BEACON_ID` to confirm the saved values.

### Archive, restore, delete

All three are free.

```bash
curl -sS -X POST https://api.synorb.com/v3/beacons/BEACON_ID/archive -H "Authorization: Bearer $SYNORB_KEY"
curl -sS -X POST https://api.synorb.com/v3/beacons/BEACON_ID/restore -H "Authorization: Bearer $SYNORB_KEY"
```

Archive is also available over MCP as `synorb-archive-beacon` with a `beacon_id`. It is idempotent. A restored Beacon returns as `draft`. To make it `active`, send `status` set to `active` with `synorb-update-beacon` or `PATCH`, then read it back. Both routes check the plan Beacon limit, as restore does. `DELETE /v3/beacons/BEACON_ID` also exists, but archive is the reversible choice, so prefer it unless your user asks for deletion.

### The `continuity` block

A bound account that runs a saved Beacon gets `briefing.continuity` on each delivery. It has the lists `new`, `seen`, `updated`, `contradictions` and `duplicates`. When `new_certain` is `false`, Synorb could not prove an item is new, and it lists the item under `possibly_new`. Each contradiction names the new and prior Manifest, the prior and new values, both Claim texts and a confidence.

Show a contradiction to the reader. Do not resolve it yourself. A demo key never gets this block, so dedupe by `manifest_id` yourself.

## Failure modes

| Error | Meaning | What to do |
| --- | --- | --- |
| `422 date_window_required` | You sent no lookback, `days` or dates. The saved default is guidance only | Add a window to the call. |
| `409 beacon_archived` | The Beacon is archived | Restore it, then run it. |
| `422 unauthorized_source_broadening` | You passed Streams, source channels or topics outside the saved scope | Remove them, or pass `broaden_sources: true` to **replace** the saved scope on purpose. |
| `422 beacon_scope_empty` | The Beacon has no saved scope and you gave none | Add `stream_ids`, `source_channel_ids` or `topic_filters` with `synorb-update-beacon` or `PATCH`. |
| `revision_mismatch` (MCP) or `409` (REST) | The Beacon changed after you read it | Read the Beacon again. Check that your change still applies. Retry with the current revision. |
| `scope_widening_refused` | Your edit adds scope or removes a topic filter | Show your user the diff. If your user agrees, retry with `allow_widening: true`. |
| `422 beacon_topic_filter_unresolvable` | A saved topic has no usable name or Tag ID | Replace it with a Tag from `GET /ontology/tags`. |
| An empty `manifests` list | A quiet window, or the window is beyond `available_through` | See the troubleshooting guide before you tell your user nothing happened. |

Do not pass `broaden_sources` only to add a topic. Extra topics on a Beacon that saved none only narrow the result, and need no flag.

## Make it good for your user

Run, show, then ask: "was this mix useful?" When they say "less research, more company news" or "add Anthropic", edit the existing Beacon and confirm what changed. Do not archive and rebuild, which wastes their Beacon count and loses its history. Always state the dates you actually covered.

## Next guide

[Parent Stream or source channel?](/agent-guides/beacon-scope-parent-stream-and-source-channel): narrow a Beacon to exactly the source channel your user means, without creating a new Stream.