Filings

Return filing metadata and SEC accession details for one ticker period.

Tier: public | Cache: cache-only | Playground: anonymous playground | Contract: 1.0.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 -G "$BASE_URL/api/filings" \
  -H "Authorization: Bearer $EDGAR_API_KEY" \
  --data-urlencode "ticker=AAPL" \
  --data-urlencode "year=2025" \
  --data-urlencode "quarter=4"


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
}
 
response = requests.get(f"{base_url}/api/filings", 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.
`filings`	`array<object>`	Discovered filings or filing metadata candidates.
`quarter`	`integer \| null`	Filing metadata or document field; verify accession and section context before citing it.
`resolved_cik`	`string \| null`	Filing metadata or document field; verify accession and section context before citing it.
`source`	`"auto" \| "8k" \| "proxy" \| "20f" \| "6k" \| null`	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

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.
Playground traffic is cache-only and scope-limited; a structured 403 cache miss means the requested filing or period is not warm for anonymous use.
Honor pagination and truncation metadata; request the next page instead of assuming the first response is complete.

Event Filings, Describe Filing, Filing Document

Generated Reference

Contract

Field	Value
Tool	`get_filings`
Method	`GET`
Path	`/api/filings`
Contract version	`1.0.0`

Parameters

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

Response Schema (200)


{
  "additionalProperties": true,
  "properties": {
    "coverage_status": {
      "anyOf": [
        {
          "enum": [
            "complete",
            "partial",
            "narrow",
            "none"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "coverage_warning": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "filings": {
      "items": {
        "additionalProperties": true,
        "properties": {
          "accession": {
            "anyOf": [
              {
                "pattern": "^\\d{10}-\\d{2}-\\d{6}$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "cik": {
            "anyOf": [
              {
                "pattern": "^\\d{1,10}$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "document_url": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "filing_date": {
            "anyOf": [
              {
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "filing_url": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "fiscal_quarter": {
            "anyOf": [
              {
                "maximum": 4.0,
                "minimum": 1.0,
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "fiscal_year": {
            "anyOf": [
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "form": {
            "minLength": 1,
            "type": "string"
          },
          "form_type": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "period_end": {
            "anyOf": [
              {
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "primary_document": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "primary_document_url": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "report_date": {
            "anyOf": [
              {
                "pattern": "^\\d{4}-\\d{2}-\\d{2}$",
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          },
          "url": {
            "anyOf": [
              {
                "minLength": 1,
                "type": "string"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "form"
        ],
        "type": "object"
      },
      "type": "array"
    },
    "quarter": {
      "anyOf": [
        {
          "maximum": 4.0,
          "minimum": 1.0,
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    },
    "resolved_cik": {
      "anyOf": [
        {
          "pattern": "^\\d{1,10}$",
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "semantic_status": {
      "anyOf": [
        {
          "enum": [
            "ok",
            "partial",
            "empty",
            "error"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "source": {
      "anyOf": [
        {
          "enum": [
            "auto",
            "8k",
            "proxy",
            "20f",
            "6k"
          ],
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "status": {
      "const": "success",
      "type": "string"
    },
    "ticker": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ]
    },
    "year": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ]
    }
  },
  "required": [
    "status"
  ],
  "type": "object"
}