> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Find Risk Factors with Semantic Search

> Use AI-powered semantic search to find relevant risk factors across SEC filings. Includes curl, Python, and JavaScript examples.

Traditional keyword search misses synonyms, paraphrases, and contextual matches. Semantic search uses embeddings to find passages that are conceptually related to your query, even when the exact words differ. This tutorial shows how to search across filing sections for risk factors using natural language.

## Prerequisites

* An SEC API key (set as `SECAPI_API_KEY`)
* Basic familiarity with REST APIs
* (Optional) Python 3.8+ or Node.js 18+ for SDK examples

## Step 1 — Run a basic semantic search

The `/v1/search/semantic` endpoint accepts a natural language query and returns the most relevant passages from SEC filings.

### curl

```bash theme={null}
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/search/semantic?q=supply%20chain%20disruption%20risks%20in%20semiconductor%20industry&limit=5"
```

### Python

```python theme={null}
import os

from secapi_client import SecApiClient

client = SecApiClient(api_key=os.environ["SECAPI_API_KEY"])

results = client.semantic_search(
    q="supply chain disruption risks in semiconductor industry",
    limit=5,
)

for hit in results["sections"]["data"]:
    print(f"[{hit.get('score', 0):.3f}] {hit.get('companyName')} ({hit.get('form')} {hit.get('filingDate')})")
    print(f"  Section: {hit.get('section_key')}")
    print(f"  {hit.get('snippet', '')[:200]}...")
    print()
```

### JavaScript

```ts theme={null}
import { SecApiClient } from "@secapi/sdk-js";

const client = new SecApiClient({
  apiKey: process.env.SECAPI_API_KEY!,
});

const results = await client.semanticSearch({
  q: "supply chain disruption risks in semiconductor industry",
  limit: 5,
});

for (const hit of results.sections.data) {
  console.log(`[${(hit.score ?? 0).toFixed(3)}] ${hit.companyName} (${hit.form} ${hit.filingDate})`);
  console.log(`  Section: ${hit.section_key}`);
  console.log(`  ${(hit.snippet ?? "").slice(0, 200)}...`);
  console.log();
}
```

### Expected output

```
[0.943] NVIDIA Corp (10-K 2024-02-21)
  Section: Risk Factors
  Our operations depend on the ability of our suppliers to deliver components
  in a timely manner. Global semiconductor supply constraints, geopolitical
  tensions, and natural disasters could materially impact...

[0.921] Advanced Micro Devices Inc (10-K 2024-01-31)
  Section: Risk Factors
  We rely on third-party manufacturers, primarily TSMC, to produce our
  products. Disruptions to our supply chain, whether due to pandemic, trade
  restrictions, or capacity constraints...

[0.908] Intel Corp (10-K 2024-01-26)
  Section: Risk Factors
  Our manufacturing operations and supply chain are subject to risks
  including shortages of materials, equipment failures, and geopolitical
  events that could affect our ability to meet customer demand...
```

## Step 2 — Scope the search to specific companies or form types

Add filters to narrow your search to a watchlist of companies or specific filing types.

### curl

```bash theme={null}
curl -H "x-api-key: $SECAPI_API_KEY" \
  "https://api.secapi.ai/v1/search/semantic?q=cybersecurity%20incident%20disclosure%20requirements&ticker=AAPL&form=10-K&limit=10"
```

### Python

```python theme={null}
results = client.semantic_search(
    q="cybersecurity incident disclosure requirements",
    ticker="AAPL",
    form="10-K",
    limit=10,
)

for hit in results["sections"]["data"]:
    print(f"{hit.get('companyName')}: {hit.get('snippet', '')[:150]}...")
```

### JavaScript

```ts theme={null}
const results = await client.semanticSearch({
  q: "cybersecurity incident disclosure requirements",
  ticker: "AAPL",
  form: "10-K",
  limit: 10,
});

for (const hit of results.sections.data) {
  console.log(`${hit.companyName}: ${(hit.snippet ?? "").slice(0, 150)}...`);
}
```

## Step 3 — Compare risk disclosures across periods

Search for the same risk factor across multiple years of filings from one company to track how their disclosure language evolves.

### Python

```python theme={null}
QUERY = "artificial intelligence regulatory risk"

for year in [2022, 2023, 2024]:
    results = client.semantic_search(
        q=QUERY,
        ticker="MSFT",
        form="10-K",
        filing_year=year,
        limit=1,
    )

    if results["sections"]["data"]:
        hit = results["sections"]["data"][0]
        print(f"--- {year} (score: {hit.get('score', 0):.3f}) ---")
        print(f"{hit.get('snippet', '')[:300]}")
        print()
    else:
        print(f"--- {year}: No matching disclosure ---")
        print()
```

### Expected output

```
--- 2022 (score: 0.812) ---
We are investing significantly in artificial intelligence capabilities. The
regulatory environment for AI is evolving and uncertain, which could affect our
ability to develop and deploy AI-powered products and services...

--- 2023 (score: 0.891) ---
The rapid adoption of generative AI technologies has increased regulatory
scrutiny globally. Proposed regulations in the EU, US, and other jurisdictions
could impose significant compliance costs and restrict certain AI applications...

--- 2024 (score: 0.934) ---
AI regulation is advancing rapidly across major markets. The EU AI Act, US
executive orders on AI safety, and emerging frameworks in Asia create a complex
compliance environment. Our AI investments face risks from divergent regulatory
requirements, potential liability frameworks, and restrictions on training data...
```

## Next steps

* **Build a risk dashboard**: Run semantic search across your portfolio holdings to surface emerging risk themes.
* **Combine with structured data**: Cross-reference risk factor mentions with financial metrics from `/v1/statements` to quantify potential impact.
* **Track disclosure changes**: Set up a quarterly job to re-run the same queries and diff the results.

See the [API Reference](/api-reference/search) for the full semantic search endpoint specification.