Better Filings

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:

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:

{
  "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.

View Markdown