Filing Evidence
Plan and retrieve citation-ready filing evidence for qualitative SEC questions.
Tier: paid | Cache: llm-call | Playground: authenticated only | Contract: 1.1.0
When To Use It
Use these tools to discover filings, inspect filing artifacts, and retrieve source-backed document evidence.
Request Examples
BASE_URL="${EDGAR_API_URL:-https://www.edgarparser.com}"
curl -sS "$BASE_URL/api/filing/evidence" \
-X POST \
-H "Authorization: Bearer $EDGAR_API_KEY" \
-H "Content-Type: application/json" \
--data '{"quarter":4,"query":"revenue recognition","source":"auto","ticker":"AAPL","year":2025}'import os
import requests
base_url = os.getenv("EDGAR_API_URL", "https://www.edgarparser.com")
headers = {"Authorization": f"Bearer {os.environ['EDGAR_API_KEY']}"}
payload = {
"quarter": 4,
"query": "revenue recognition",
"source": "auto",
"ticker": "AAPL",
"year": 2025
}
response = requests.post(f"{base_url}/api/filing/evidence", headers=headers, json=payload, 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. |
warnings | array<string> | Non-fatal issues that should be surfaced or handled by the agent. |
coverage | object | Filing metadata or document field; verify accession and section context before citing it. |
evidence | array<object> | Filing metadata or document field; verify accession and section context before citing it. |
planner_trace | object | Filing metadata or document field; verify accession and section context before citing it. |
source_pack | object | Filing metadata or document field; verify accession and section context before citing it. |
suggested_next_reads | array<object> | Filing metadata or document field; verify accession and section context before citing it. |
Response Fields To Inspect
accession,filing_url, form type, and period fields to confirm the filing identity.- Pagination or truncation fields before assuming the returned text is complete.
- Section titles and document names when citing prose back to the filing.
Errors And Coverage
401or403: 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.- Paid or LLM-backed paths should be used only when cheaper fact, filing, table, or text tools cannot answer the question.
- Honor pagination and truncation metadata; request the next page instead of assuming the first response is complete.
Related Tools
Filing Document, Search Filing Text, Cite Concept
Generated Reference
Contract
| Field | Value |
|---|---|
| Tool | get_filing_evidence |
| Method | POST |
| Path | /api/filing/evidence |
| Contract version | 1.1.0 |
Parameters
| Name | Location | Required | Type | Notes |
|---|---|---|---|---|
| none | - | - | - | - |
Request Body Schema
{
"additionalProperties": false,
"properties": {
"filing_date_from": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"filing_date_to": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"form_types": {
"items": {
"type": "string"
},
"type": "array"
},
"include_full_sections": {
"default": false,
"type": "boolean"
},
"include_planner_trace": {
"default": false,
"type": "boolean"
},
"max_hits": {
"default": 12,
"maximum": 100.0,
"minimum": 1.0,
"type": "integer"
},
"quarter": {
"type": "integer"
},
"query": {
"type": "string"
},
"related_tickers": {
"items": {
"type": "string"
},
"type": "array"
},
"source": {
"default": "auto",
"type": "string"
},
"task_intent": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"ticker": {
"type": "string"
},
"year": {
"type": "integer"
}
},
"required": [
"ticker",
"year",
"quarter",
"query"
],
"type": "object"
}Response Schema (200)
{
"properties": {
"coverage": {
"properties": {
"cache_status": {
"const": "cold",
"type": "string"
},
"confidence": {
"enum": [
"low",
"medium",
"high"
],
"type": "string"
},
"coverage_status": {
"enum": [
"complete",
"partial",
"narrow",
"none"
],
"type": "string"
},
"evidence_layers_consulted": {
"items": {
"type": "string"
},
"type": "array"
},
"matched_intent": {
"type": "string"
},
"missing_or_unavailable": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"searched_earnings_releases": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"searched_event_filings": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"searched_extractions": {
"items": {
"type": "string"
},
"type": "array"
},
"searched_sections": {
"items": {
"type": "string"
},
"type": "array"
},
"searched_tables": {
"items": {
"type": "string"
},
"type": "array"
},
"semantic_status": {
"enum": [
"ok",
"partial",
"empty",
"error"
],
"type": "string"
},
"source_families": {
"additionalProperties": true,
"type": "object"
},
"source_pack_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
}
},
"required": [
"matched_intent",
"source_pack_version",
"searched_sections",
"searched_tables",
"searched_extractions",
"missing_or_unavailable",
"evidence_layers_consulted",
"confidence",
"semantic_status",
"coverage_status"
],
"type": "object"
},
"evidence": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"planner_trace": {
"properties": {
"matched_intent": {
"type": "string"
},
"optional_reads": {
"items": {
"properties": {
"rationale": {
"type": "string"
},
"section": {
"type": "string"
},
"subsections": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"section",
"subsections",
"rationale"
],
"type": "object"
},
"type": "array"
},
"rationale": {
"type": "string"
},
"recommended_sources": {
"items": {
"properties": {
"rationale": {
"type": "string"
},
"section": {
"type": "string"
},
"subsections": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"section",
"subsections",
"rationale"
],
"type": "object"
},
"type": "array"
},
"required_reads": {
"items": {
"properties": {
"rationale": {
"type": "string"
},
"section": {
"type": "string"
},
"subsections": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"section",
"subsections",
"rationale"
],
"type": "object"
},
"type": "array"
},
"source_pack_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"matched_intent",
"source_pack_version",
"recommended_sources",
"required_reads",
"optional_reads",
"warnings",
"rationale"
],
"type": "object"
},
"source_pack": {
"properties": {
"matched_intent": {
"type": "string"
},
"optional_reads": {
"items": {
"properties": {
"rationale": {
"type": "string"
},
"section": {
"type": "string"
},
"subsections": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"section",
"subsections",
"rationale"
],
"type": "object"
},
"type": "array"
},
"rationale": {
"type": "string"
},
"recommended_sources": {
"items": {
"properties": {
"rationale": {
"type": "string"
},
"section": {
"type": "string"
},
"subsections": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"section",
"subsections",
"rationale"
],
"type": "object"
},
"type": "array"
},
"required_reads": {
"items": {
"properties": {
"rationale": {
"type": "string"
},
"section": {
"type": "string"
},
"subsections": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"section",
"subsections",
"rationale"
],
"type": "object"
},
"type": "array"
},
"source_pack_version": {
"anyOf": [
{
"type": "string"
},
{
"type": "null"
}
]
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"matched_intent",
"source_pack_version",
"recommended_sources",
"required_reads",
"optional_reads",
"warnings",
"rationale"
],
"type": "object"
},
"status": {
"const": "success",
"type": "string"
},
"suggested_next_reads": {
"items": {
"additionalProperties": true,
"type": "object"
},
"type": "array"
},
"warnings": {
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"status",
"evidence",
"coverage",
"source_pack",
"suggested_next_reads",
"warnings"
],
"type": "object"
}