POST/filing-intelligence/screen

Cross-company screening by qualitative signals extracted from SEC filings, 8-Ks, transcripts and IR. Filters by verifiable, typed facts (with evidence and section pointers) — never by LLM-generated scores. Mirrors the MCP screen_filing_signals tool.

Endpoint

POST https://api.metricduck.com/api/v1/filing-intelligence/screen

Request Body

Parameter	Type	Default	Description
`signals`required	`string[]`	-	Signal ids to match, e.g. ["material_weakness", "tone_cautious"].
`ticker`	`string`	-	Restrict to a single company (per-ticker signal inventory).
`sectors`	`string[]`	-	Sector codes to filter by (e.g., ["TECH", "FIN"]).
`recency_days`	`integer`	`90`	Only filings from the last N days (1–365).
`match_mode`	`string`	`"all"`	"all" (every signal on the same row) or "any" (any signal).
`order_by`	`string`	`"recency"`	"recency" or "market_cap" (high-impact first).
`since_date / until_date`	`string`	-	Explicit date range (YYYY-MM-DD); overrides recency_days.
`limit`	`integer`	`20`	Max results (1–50).

Common signals

A representative set; the signal catalog is broader and id-agnostic.

tone_cautiousManagement tone is cautious or defensive

customer_concentration_highCustomer concentration exceeds 20% or elevated risk

covenant_riskDebt covenant tight, waiver obtained, or violation

guidance_revisedGuidance raised, lowered, or withdrawn

has_material_chargeMaterial non-recurring charge or write-down

Example Request Body

{
  "signals": ["material_weakness", "tone_cautious"],
  "match_mode": "any",
  "recency_days": 90,
  "limit": 10
}

Response

Fields

Field	Type	Description
`total`	`integer`	Number of matches returned.
`signals_requested`	`string[]`	Echo of the requested signal ids.
`matches`	`array`	Matched companies (see fields below).
`matches[].ticker`	`string`	Company ticker.
`matches[].company_name`	`string`	Company name.
`matches[].form_type`	`string`	Source form type (10-K, 10-Q, 8-K, transcript, IR).
`matches[].filing_date`	`string`	Filing / event date.
`matches[].matched_signals`	`string[]`	Which requested signals fired on this row.
`matches[].accession_number`	`string`nullable	Source filing accession (for citation).
`matches[].source_url`	`string`nullable	Source URL for IR press-release matches.

Example Response

{
  "total": 2,
  "signals_requested": ["material_weakness", "tone_cautious"],
  "matches": [
    {
      "ticker": "EXMP",
      "company_name": "Example Corp",
      "sector": "TECH",
      "form_type": "10-K",
      "filing_date": "2026-03-12",
      "fiscal_period": "FY2025",
      "matched_signals": ["material_weakness"],
      "accession_number": "0001234567-26-000045"
    }
  ]
}

cURL

curl -X POST "https://api.metricduck.com/api/v1/filing-intelligence/screen" \
  -H "Authorization: Bearer fda_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"signals": ["material_weakness", "tone_cautious"], "match_mode": "any", "limit": 10}'

Notes

- Public — callable without a key (guest caps); a free key raises the caps and daily quota.
- Signals are typed facts with evidence and section pointers — not opinion scores.
- Matches span sources: 10-K/10-Q, 8-K, earnings transcripts, IR press releases.
- accession_number (+ cik) on filing/transcript matches lets you cite back to the source.