Search Filing Tables

Search cached filing table metadata across a ticker and period range.

Tier: public | Cache: cache-only | Playground: authenticated only | Contract: 1.0.0

When To Use It

Use these tools when the answer depends on tables embedded in filing documents rather than normalized XBRL facts.

Request Examples


BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
 
curl -sS -G "$BASE_URL/api/tables/search" \
  -H "Authorization: Bearer $EDGAR_API_KEY" \
  --data-urlencode "ticker=AAPL"


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"
}
 
response = requests.get(f"{base_url}/api/tables/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.
`semantic_status`	`"ok" \| "partial" \| "empty" \| "error" \| null`	Whether the response is semantically usable, partial, empty, or errored.
`coverage_status`	`"complete" \| "partial" \| "narrow" \| "none" \| null`	Completeness signal; do not present partial or narrow coverage as complete.
`coverage_warning`	`string \| null`	Human-readable explanation of missing or ambiguous coverage.
`matches`	`array<object>`	Candidate fact matches; inspect labels, units, periods, and source references.
`candidate_filings_count`	`integer`	Count field; use it to detect empty, partial, or unexpectedly broad output.
`filings_missing_cache`	`array<object>`	Table result field; preserve row labels, column labels, and units when answering.
`filings_missing_cache_count`	`integer`	Count field; use it to detect empty, partial, or unexpectedly broad output.

Response Fields To Inspect

table_id, title, section, and accession before using a table as evidence.
Row labels, column labels, units, and footnotes instead of inferring meaning from position alone.
Pagination or match-score fields when search returns multiple candidate tables.

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 Tables, Compare Filing Tables, Search Filing Text

Generated Reference

Contract

Field	Value
Tool	`search_filing_tables`
Method	`GET`
Path	`/api/tables/search`
Contract version	`1.0.0`
Schema fingerprint	`sha256:94335e68424294db09cdf6e536449e7fb80f47f9a8b4fcfb9290161158e2168f`

Parameters

Name	Location	Required	Type
`ticker`	query	yes	`string`
`description`	query	no	`string \| null`
`table_type`	query	no	`string \| null`
`period_from`	query	no	`string \| null`
`period_to`	query	no	`string \| null`
`form_type`	query	no	`string \| null`
`source`	query	no	`string`
`section_key`	query	no	`string \| null`
`rebuild_index`	query	no	`boolean`
`limit`	query	no	`integer`

Response Schema (200)


{
  "additionalProperties": true,
  "properties": {
    "candidate_filings_count": {
      "type": "integer"
    },
    "coverage_status": {
      "anyOf": [
        {
          "enum": [
            "complete",
            "partial",
            "narrow",
            "none"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage_warning": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "filings_missing_cache": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "type": "array"
    },
    "filings_missing_cache_count": {
      "type": "integer"
    },
    "filings_with_cache_count": {
      "type": "integer"
    },
    "index_entries_total": {
      "type": "integer"
    },
    "index_last_updated": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "index_rebuilt": {
      "default": false,
      "type": "boolean"
    },
    "matches": {
      "items": {
        "additionalProperties": true,
        "properties": {
          "accession": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "citation_state": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "filing_date": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "filing_url": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "form_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "period": {
            "type": "string"
          },
          "period_end": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "quarter": {
            "type": "integer"
          },
          "section_key": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "source": {
            "enum": [
              "auto",
              "8k",
              "proxy",
              "20f",
              "6k"
            ],
            "type": "string"
          },
          "table_id": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "table_type": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "ticker": {
            "type": "string"
          },
          "year": {
            "type": "integer"
          }
        },
        "required": [
          "ticker",
          "period",
          "year",
          "quarter",
          "source"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "matches_count": {
      "type": "integer"
    },
    "query": {
      "additionalProperties": true,
      "type": "object"
    },
    "searched_periods": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": {
              "type": "integer"
            },
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ]
    },
    "semantic_status": {
      "anyOf": [
        {
          "enum": [
            "ok",
            "partial",
            "empty",
            "error"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "const": "success",
      "type": "string"
    }
  },
  "required": [
    "status",
    "index_entries_total",
    "candidate_filings_count",
    "filings_with_cache_count",
    "filings_missing_cache_count",
    "matches_count"
  ],
  "type": "object"
}