---
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: 17
updated: 2026-10-07
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, and every change is a `PATCH` to the same Beacon, never an 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, "response_profile": "slim"}'
```

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": "digest", "max_items": 5},
    "quota": {"manifests_billed_this_call": 1}
  }
}
```

### Edit in place

`PATCH` replaces each field you send and leaves the others alone. Read the Beacon first, and when you replace `topic_filters`, keep the entries you still want. There is no MCP tool for editing, so edits go over REST:

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

Then call `GET /v3/beacons/BEACON_ID` to confirm the saved values. The editable fields include `name`, `description`, `natural_language_intent`, `stream_ids`, `source_channel_ids`, `topic_filters`, `default_date_window` and `status`.

### 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`. If you want `active`, `PATCH` it and read it back. `DELETE /v3/beacons/BEACON_ID` also exists, but archive is the reversible choice, so prefer it unless your user asks for deletion.

## 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 `PATCH`. |
| `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", `PATCH` 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-resources/beacon-scope-parent-stream-and-source-channel): narrow a Beacon to exactly the source channel your user means, without creating a new Stream.