Find Risk Factors with Semantic Search

Use semantic search when a literal phrase is too narrow for a disclosure question, such as supply-chain exposure across a company’s 10-Ks. Search rank is a navigation aid, not a finding of materiality, completeness, or legal risk. The completed workflow creates a cited research queue, then asks a reviewer to read the source section in context.

Prerequisites

SECAPI_API_KEY, curl, and jq, or Node.js 18+.
A question with a company and filing scope. This example examines NVIDIA 10-K risk language.

export SECAPI_API_KEY="your_api_key"

1. Run a bounded hybrid search

curl --get --fail-with-body -H "x-api-key: $SECAPI_API_KEY" \
  --data-urlencode "q=supply chain disruption risk" \
  --data-urlencode "ticker=NVDA" --data-urlencode "form=10-K" \
  --data-urlencode "mode=hybrid" --data-urlencode "view=agent" --data-urlencode "limit=10" \
  "https://api.secapi.ai/v1/search/semantic" \
  | jq '{query, mode, sections, requestId, traceparent}'

The expected result is a ranked sections.data list with citation-preserving fields such as accession, source URL, section key, character offsets, and highlighted snippet. Open the cited filing before quoting or scoring it.

2. Compare the same question across annual filings

Create compare-risk-factors.mjs to keep filters and evidence consistent.

const headers = { "x-api-key": process.env.SECAPI_API_KEY ?? "" };
if (!headers["x-api-key"]) throw new Error("SECAPI_API_KEY is required");
for (const filingYear of [2023, 2024, 2025]) {
  const query = new URLSearchParams({ q: "artificial intelligence regulatory risk", ticker: "MSFT",
    form: "10-K", filing_year: String(filingYear), mode: "hybrid", view: "agent", limit: "5" });
  const response = await fetch(`https://api.secapi.ai/v1/search/semantic?${query}`, { headers });
  if (!response.ok) throw new Error(`${response.status}: ${await response.text()}`);
  const payload = await response.json();
  console.log(JSON.stringify({ filingYear, requestId: payload.requestId,
    citations: (payload.sections?.data ?? []).map(({ accession, source_url, section_key, char_start, char_end, highlighted_snippet }) =>
      ({ accession, source_url, section_key, char_start, char_end, highlighted_snippet })) }, null, 2));
}

Run node compare-risk-factors.mjs. The expected output is a cited research queue for each filing year, including any degraded citation fields, not a change score.

Common errors and false positives

q is required; valid modes are keyword, semantic, and hybrid, while limit is 1-100.
Empty results may reflect a too-narrow issuer/form/year scope or sparse indexed language, not the absence of a risk.
A changed rank, snippet, or wording is a lead. Compare like-for-like reporting periods and read the full cited section.
Do not drop accession, URL, section key, offsets, or request ID; without them a reviewer cannot reproduce the result.

Production considerations

Store the query, mode, filters, response timestamp, request metadata, and every citation field. Cache recurring searches, cap the number of results sent to reviewers, and keep model-generated interpretation clearly separate from cited disclosure text.

Next action

Retrieve the cited filing section and build a reviewer decision record that explains whether the disclosure changed in substance.

Build a Filing Monitor with Webhooks Compare executive compensation

​Prerequisites

​1. Run a bounded hybrid search

​2. Compare the same question across annual filings

​Common errors and false positives

​Production considerations

​Next action