GET /v1/search/semantic - SEC API for AI

curl -X GET -H "x-api-key: $SECAPI_API_KEY" -H "secapi-version: 2026-03-19" "https://api.secapi.ai/v1/search/semantic?q=liquidity%20risk&ticker=EXAMPLE&form=10-K&mode=hybrid&limit=10"

{
  "object": "semantic_search",
  "query": "liquidity risk",
  "mode": "hybrid",
  "sections": {
    "object": "list",
    "data": [
      {
        "object": "section",
        "id": "sec_example_2025_10k_item_7",
        "ticker": "EXAMPLE",
        "form": "10-K",
        "key": "item_7",
        "title": "Management's Discussion and Analysis",
        "snippet": "Example discussion of liquidity risk and capital resources.",
        "accession": "example-accession",
        "section_key": "item_7",
        "char_start": 22,
        "char_end": 36,
        "highlighted_snippet": "Example discussion of **liquidity risk** and capital resources.",
        "source_url": "https://example.com/sec-filings/example-2025-10-k",
        "score": 0.8421,
        "retrievalMode": "hybrid",
        "provenance": {
          "source": "example",
          "sourceLabel": "Illustrative response - not a live SEC filing",
          "accessionNumber": null,
          "filingUrl": "https://example.com/sec-filings/example-2025-10-k",
          "retrievedAt": "2026-02-20T00:00:00.000Z",
          "parserVersion": "example"
        }
      }
    ],
    "count": 1,
    "degradedState": null
  },
  "requestId": "req_2ZK8Q1W9F4M6P7R3",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Retrieve filing passages that are conceptually related to a finance question, with hybrid keyword and vector retrieval plus source citation fields on every result row.

Audience: application and coding agent.

Citation fields

Every result row carries seven additive top-level fields:

Field	Description
`accession`	SEC accession number for the source filing
`section_key`	Canonical section identifier (e.g. `item_1a`)
`char_start` / `char_end`	Half-open offsets into the section markdown text (`section_snippets.content_md`) — section-text-relative, stable across reparses
`highlighted_snippet`	±150 char window with query terms wrapped in `…`, sentence-boundary truncated, ≤320 chars
`source_url`	Public SEC.gov filing URL
`ticker`	Issuer ticker, when known

When the validator can’t produce a span (no section text, no query-term match, or offsets out of bounds), char_start/char_end/highlighted_snippet drop to null and _citation_degraded records the reason. Identity fields (accession, section_key, source_url, ticker) are always populated when known. See api conventions → citation + char-range spans for the full contract.

Retrieval and scope

q is required. mode=hybrid is the default and combines keyword and vector retrieval; use keyword or semantic only when intentionally comparing retrieval behavior. Narrow the candidate set with one issuer identifier, form, or filing_year before asking a narrowly scoped question. The result is evidence discovery, not an answer or investment conclusion. Use source_url, accession, section_key, and character offsets to let a downstream reader verify the cited passage in context.

Semantic risk-factor tutorial

Build a source-cited risk-factor retrieval workflow.

Semantic search API guide

Compare query framing and retrieval modes.

Agent mode

Pass ?view=agent to drop score and retrievalMode from each row. The seven citation fields are preserved unconditionally. See api conventions → response formats for the full ?view= contract.

Canonical metadata

requestId
traceparent

Example request

curl -X GET -H "x-api-key: $SECAPI_API_KEY" -H "secapi-version: 2026-03-19" "https://api.secapi.ai/v1/search/semantic?q=liquidity%20risk&ticker=EXAMPLE&form=10-K&mode=hybrid&limit=10"

Example response

{
  "object": "semantic_search",
  "query": "liquidity risk",
  "mode": "hybrid",
  "sections": {
    "object": "list",
    "data": [
      {
        "object": "section",
        "id": "sec_example_2025_10k_item_7",
        "ticker": "EXAMPLE",
        "form": "10-K",
        "key": "item_7",
        "title": "Management's Discussion and Analysis",
        "snippet": "Example discussion of liquidity risk and capital resources.",
        "accession": "example-accession",
        "section_key": "item_7",
        "char_start": 22,
        "char_end": 36,
        "highlighted_snippet": "Example discussion of **liquidity risk** and capital resources.",
        "source_url": "https://example.com/sec-filings/example-2025-10-k",
        "score": 0.8421,
        "retrievalMode": "hybrid",
        "provenance": {
          "source": "example",
          "sourceLabel": "Illustrative response - not a live SEC filing",
          "accessionNumber": null,
          "filingUrl": "https://example.com/sec-filings/example-2025-10-k",
          "retrievedAt": "2026-02-20T00:00:00.000Z",
          "parserVersion": "example"
        }
      }
    ],
    "count": 1,
    "degradedState": null
  },
  "requestId": "req_2ZK8Q1W9F4M6P7R3",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

About this example

This response uses a synthetic issuer, accession, and example.com URL to illustrate the citation envelope. It does not identify or quote a live SEC filing.

Give this prompt to your agent

Failure posture

use only keyword, semantic, or hybrid for mode; invalid values return accepted values in the validation details
send ticker or its symbol alias, not conflicting values for both
treat missing or degraded citation spans as a reason to verify the linked source, not to fabricate a quote
preserve requestId and traceparent when retrying a transient failure

​Citation fields

​Retrieval and scope

​Related guides

Semantic risk-factor tutorial

Semantic search API guide

​Agent mode

​Canonical metadata

​Example request

​Example response

​About this example

​Give this prompt to your agent

​Failure posture

Citation fields

Retrieval and scope

Related guides

Agent mode

Canonical metadata

Example request

Example response

About this example

Give this prompt to your agent

Failure posture