# Finding filings

## CLI

Run `betterfilings filing search --help` for the current input contract.

1. Run `betterfilings company search NAME --json` and choose the intended listing by name, ticker, exchange, and country.
2. Pass the selected `listingId` to `betterfilings filing search`. Use `--input FILE|-` for structured filters.
3. Follow the returned cursor unchanged for the next page.
4. Run `betterfilings filing get FILING_ID --json` and choose an explicit artifact key.

## Hosted MCP

Use `company_search`, then `filing_search`, then `filing_get`. `filing_search` accepts exactly one selector: `companyScreen`, `listingIds`, or `watchlistId`. It searches metadata, not filing contents. Use `document_search` only after selecting documents.

## Annual filing example (CLI or MCP input)

The dates below are illustrative. Update the window end to the date you are checking and keep each interval at most one year. For annual EDGAR filings, substitute the selected UUID from company search for `RETURNED_LISTING_ID`, then run this explicit request. The date range is under one year, so it does not silently use the 90-day default:

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

Save that object as `annual-filings.json` and run `betterfilings filing search --input annual-filings.json --json`. To check the immediately preceding period, use the adjacent window `since: "2024-09-15"` and `until: "2025-09-14"`; never request more than one year at once.

Save the first response to `page-1.json` using shell redirection or `--output page-1.json`. If a response contains a non-null `data.nextCall`, its `arguments` object is the next CLI input. With jq available, for example, `jq '.data.nextCall.arguments' page-1.json | betterfilings filing search --input - --json`. Do not pass the whole `nextCall` envelope to `--input`.

The default filing window is 90 days. Explicit windows can span at most one year, pages contain at most 50 results, and `sort` is `newest` or `oldest`. Preserve partial-source status and unsupported-listing warnings; an empty partial result is not complete coverage.