Search Filing Text

Search cached markdown within one filing and return matching spans.

Tier: registered | Cache: cache-only | Playground: authenticated only | Contract: 1.1.0

When To Use It

Use text search when the caller needs prose evidence from filing sections and already knows the filing scope.

Request Examples


BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
 
curl -sS -G "$BASE_URL/api/filing/text/search" \
  -H "Authorization: Bearer $EDGAR_API_KEY" \
  --data-urlencode "ticker=AAPL" \
  --data-urlencode "year=2025" \
  --data-urlencode "quarter=4" \
  --data-urlencode "query=revenue recognition"


import os
import requests
 
base_url = os.getenv("EDGAR_API_URL", "https://www.edgarparser.com")
headers = {"Authorization": f"Bearer {os.environ['EDGAR_API_KEY']}"}
params = {
  "ticker": "AAPL",
  "year": 2025,
  "quarter": 4,
  "query": "revenue recognition"
}
 
response = requests.get(f"{base_url}/api/filing/text/search", headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

Key Response Fields

Field	Type	Why It Matters
`status`	`const "success"`	Transport-level success indicator inside the JSON response.
`form_type`	`string \| null`	SEC form type; verify it matches the requested filing class.
`cache_status`	`"warm" \| "partial" \| "cold"`	Response field to inspect before using the output in an answer.
`citation_state`	`const "legacy_proxy_cache"`	Response field to inspect before using the output in an answer.
`filing`	`object`	Response field to inspect before using the output in an answer.
`hits`	`array<object>`	Response field to inspect before using the output in an answer.
`hits_count`	`integer`	Count field; use it to detect empty, partial, or unexpectedly broad output.
`markdown_chars_searched`	`integer`	Response field to inspect before using the output in an answer.

Response Fields To Inspect

Matched section, accession, and snippet text before quoting or summarizing.
Pagination fields when the search result set is longer than one page.
The original filing context when a phrase appears in multiple sections.

Errors And Coverage

401 or 403: the API key is missing, expired, or not allowed to use this tier.
429: retry after the rate-limit window, and prefer broader batch or series tools over repeated single-period calls.
This tool is cache-only; if the target filing is not warm, warm it through an allowed paid path before retrying.
Honor pagination and truncation metadata; request the next page instead of assuming the first response is complete.

Filing Document, Filing Evidence, Filing Sections

Generated Reference

Contract

Field	Value
Tool	`search_filing_text`
Method	`GET`
Path	`/api/filing/text/search`
Contract version	`1.1.0`

Parameters

Name	Location	Required	Type
`ticker`	query	yes	`string`
`year`	query	yes	`integer`
`quarter`	query	yes	`integer`
`source`	query	no	`string`
`query`	query	yes	`string`

Response Schema (200)


{
  "properties": {
    "cache_status": {
      "enum": [
        "warm",
        "partial",
        "cold"
      ],
      "type": "string"
    },
    "citation_state": {
      "const": "legacy_proxy_cache",
      "type": "string"
    },
    "filing": {
      "additionalProperties": true,
      "type": "object"
    },
    "form_type": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "hits": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    },
    "hits_count": {
      "type": "integer"
    },
    "markdown_chars_searched": {
      "type": "integer"
    },
    "query": {
      "properties": {
        "quarter": {
          "type": "integer"
        },
        "query": {
          "type": "string"
        },
        "source": {
          "enum": [
            "auto",
            "8k",
            "proxy",
            "20f",
            "6k"
          ],
          "type": "string"
        },
        "ticker": {
          "type": "string"
        },
        "year": {
          "type": "integer"
        }
      },
      "required": [
        "ticker",
        "year",
        "quarter",
        "source",
        "query"
      ],
      "type": "object"
    },
    "searched_sections": {
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "status": {
      "const": "success",
      "type": "string"
    }
  },
  "required": [
    "status",
    "query",
    "filing",
    "form_type",
    "searched_sections",
    "hits_count",
    "cache_status",
    "markdown_chars_searched",
    "hits"
  ],
  "type": "object"
}