# Monitoring companies

Watchlists store stable listing IDs for repeat filing searches. They do not create background alerts or ingestion cursors.

## CLI

Run `betterfilings watchlist create --help` and `betterfilings watchlist add --help` for the current arguments. Watchlist changes require write authorization; if the current credential is read-only, start a new email-code login with `betterfilings auth request --email ADDRESS --allow-write`, then `betterfilings auth verify --otp-stdin`. Keep the same host on both commands. Request write access only when the user has authorized watchlist changes.

Create a watchlist, then use only IDs returned by the preceding commands:

```sh
betterfilings watchlist create "Annual filings" --json
betterfilings company search "COMPANY_NAME" --json
betterfilings watchlist add RETURNED_WATCHLIST_ID RETURNED_LISTING_ID --json
```

Replace `RETURNED_WATCHLIST_ID` with the `id` returned by watchlist creation and `RETURNED_LISTING_ID` with the chosen company-search `listingId`. The uppercase values are placeholders, not example results.

Then save this as `watchlist-filings.json`, substituting the returned watchlist UUID:

```json
{
  "watchlistId": "RETURNED_WATCHLIST_ID",
  "edgarForms": ["10-K"],
  "since": "2025-09-15",
  "until": "2026-09-14",
  "sort": "newest",
  "limit": 50
}
```

Run `betterfilings filing search --input watchlist-filings.json --json`. This explicit window avoids the 90-day default. For older history, make separate adjacent requests of at most one year, such as `2024-09-15` through `2025-09-14`.

## Hosted MCP

Use the corresponding `watchlist_*` tools, then call `filing_search` with only `watchlistId` as its selector. Follow the returned global cursor without changing filters or sort order.

## Durable monitoring loop

1. Establish a baseline set of seen canonical filing IDs. Keep pending notifications separately.
2. On every scheduled run, query an overlapping publication-date window so boundary filings are rechecked.
3. Finish every returned `nextCall` page before declaring the run successful.
4. Deduplicate by filing ID and notify only for IDs absent from the durable seen set.
5. After notifications succeed, move those IDs from pending to seen and advance the saved successful-run time.
6. If any page, source, or notification fails, keep pending items and retry without advancing saved state.

Scheduling and notifications belong to the external agent environment. Late-ingested filings older than the overlap window may be missed, so choose the overlap for the workflow and state that limitation.