secedgar-mcp-server
An MCP server that allows agents to query SEC EDGAR filings, retrieve XBRL financial data, and analyze company information. It supports searching filings since 1993, fetching document text, comparing financials across companies, and tracing ownership through insider trades and institutional holdings.
Endpoint and access
No sign-in to connect and list tools. Individual tools may still need a vendor account, credentials, or permissions; check the documented prerequisites.
MCP endpoint (Streamable HTTP)
https://secedgar.caseyjhand.com/mcpWhat its tools do
16 tools, grouped by the hints the server advertises. Hints are self-declared, not verified behavior.
Read-only (16)
secedgar_company_searchsecedgar_search_filingssecedgar_get_filingsecedgar_get_financialssecedgar_get_snapshotsecedgar_get_material_eventssecedgar_get_insider_transactionssecedgar_get_institutional_holdingssecedgar_find_holderssecedgar_get_beneficial_ownerssecedgar_get_fund_holdingssecedgar_fetch_framessecedgar_compare_companiessecedgar_search_conceptssecedgar_dataframe_describesecedgar_dataframe_query
Checks and signals
Each line is separate evidence, not a trust score.
- Passed Endpoint answered the live check ·
- Availability 1 of 1 checks passed in 30 days
What you can do with it
- Search SEC EDGAR filings by ticker, name, or CIK
- Retrieve historical XBRL financial data for a company
- Fetch specific filing metadata and document text
- Analyze insider transactions and institutional holdings
Source and maintenance
Community listingRegistry 0.18.1
- Maintenance checked
Protocol and capabilities
- Server
- secedgar-mcp-server 0.18.1
- MCP protocol negotiated in check
- 2025-11-25
- Tools
- 16 advertised
- Resources
- 3 advertised
- Resource templates
- 1 advertised
- Prompts
- 1 advertised
Server-advertised capabilities
{
"tools": {
"listChanged": true
},
"logging": {},
"prompts": {
"listChanged": true
},
"resources": {
"subscribe": true,
"listChanged": true
},
"extensions": {
"io.modelcontextprotocol/skills": {
"directoryRead": true
}
}
}Server-provided instructions
Untrusted server output shown for inspection. It is not Koskamo guidance and is excluded from knowledge search.
Tools
16 advertised
secedgar_company_search — Secedgar Company Search
Advertised read-onlyOpen-world
Find companies and retrieve entity info with optional recent filings. Entry point for most EDGAR workflows — resolves tickers, names, or CIKs to entity details, with accession numbers in the result feeding secedgar_get_filing for document content. When a date or form filter carries the scan past the recent submissions window, the full filtered filing history is also staged as df_<id> — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.
secedgar_company_search input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"query"
],
"properties": {
"forms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter filings to specific form types (e.g., [\"10-K\", \"10-Q\", \"8-K\"]), matched exactly (case-insensitive) — list an amendment such as \"10-K/A\" to include it. Without this, returns all form types."
},
"query": {
"type": "string",
"minLength": 1,
"description": "Company ticker symbol (e.g., \"AAPL\", \"VOO\"), name (e.g., \"Apple\"), or CIK number (e.g., \"320193\"). Ticker is the fastest lookup and works for equities, ETFs, and mutual funds; a multi-class share ticker resolves in either form (\"BRK-B\" or \"BRK.B\"). Name search matches current and former names, preferring a name the query matches exactly over one it only starts or appears in, and never matching from inside a word (\"SY Bancorp\" does not find \"Embassy Bancorp\"); an exact or starts-with match ignores commas, periods, apostrophes, extra spaces, and the spaces between single initials (\"QXO Inc\" finds \"QXO, Inc.\"; \"U.S. Bancorp\" finds \"US BANCORP\"; \"Macys\" finds \"Macy's, Inc.\"; \"JM Smucker\" finds \"J M SMUCKER Co\"). The corporate suffix (Inc, Corp, Co, Ltd, PLC, LLC, LP, N.V., S.A., AG, SE) can be left off (\"Apple\" finds \"Apple Inc.\"; \"Rio Tinto\" lists both the Ltd and the PLC) or spelled out (\"Beacon Financial Corporation\" finds \"Beacon Financial Corp\"), but a suffix you include must match — Corp, Inc, Co, and Ltd stay distinct from each other, since separate registrants differ only by which one they use."
},
"filed_after": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches filings that predate the recent window — the last year or 1,000 filings, whichever holds more (e.g. a company's 2005 10-K)."
},
"filed_before": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan."
},
"filing_limit": {
"type": "integer",
"default": 10,
"maximum": 1000,
"minimum": 1,
"description": "Maximum number of filings to return in the inline list; when more match, the notice names where the rest are. Capped at 50: a larger value, up to 1000, returns what 50 returns."
},
"include_filings": {
"type": "boolean",
"default": true,
"description": "Include recent filings in the response. Set to false for entity-info-only lookups."
}
},
"additionalProperties": false
}secedgar_company_search output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"cik",
"name",
"tickers",
"exchanges",
"sic",
"sic_description"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The inline limit applied: `filing_limit`, at most 50."
},
"cik": {
"type": "string",
"description": "Central Index Key, zero-padded to 10 digits."
},
"sic": {
"type": "string",
"description": "SIC industry code."
},
"name": {
"type": "string",
"description": "SEC-conformed company name."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"no_match",
"ambiguous_company",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `no_match`: No company matches the query. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of filings returned inline."
},
"notice": {
"type": "string",
"description": "Guidance when no filings matched the forms filter, or when the inline list withheld some — naming the dataframe, a larger filing_limit, or a secedgar_search_filings call to page through the rest."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"truncated": {
"type": "boolean",
"description": "True when the archive scan hit its page cap, so older matching filings exist beyond the dataframe."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of the full filtered history (recent window plus archive pages), staged only when the scan went past the recent window and the history exceeds the inline list (filing_limit, at most 50).",
"additionalProperties": false
},
"filings": {
"type": "array",
"items": {
"type": "object",
"required": [
"accession_number",
"form",
"filing_date",
"primary_document"
],
"properties": {
"form": {
"type": "string",
"description": "Form type (e.g., 10-K)."
},
"description": {
"type": "string",
"description": "SEC-provided filing description. Absent when SEC published none."
},
"filing_date": {
"type": "string",
"description": "Date the filing was submitted (YYYY-MM-DD)."
},
"report_date": {
"type": "string",
"description": "Period of report (YYYY-MM-DD). Absent for forms without one (proxy statements, ownership reports)."
},
"accession_number": {
"type": "string",
"description": "Accession number, dash format (e.g., 0000320193-23-000106). Pass to secedgar_get_filing."
},
"primary_document": {
"type": "string",
"description": "Primary document filename."
}
},
"description": "One filing record with form type, dates, and primary document.",
"additionalProperties": false
},
"description": "Recent filings, filtered by forms if specified."
},
"tickers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Associated ticker symbols."
},
"class_id": {
"type": "string",
"description": "SEC fund class ID (e.g. \"C000092055\"), present alongside series_id."
},
"exchanges": {
"type": "array",
"items": {
"type": "string"
},
"description": "Exchanges where listed."
},
"series_id": {
"type": "string",
"description": "SEC fund series ID (e.g. \"S000002839\"), when the query resolved via a fund ticker (ETF or mutual fund)."
},
"truncated": {
"type": "boolean",
"description": "True when more filings matched than the inline list holds."
},
"total_filings": {
"type": "number",
"description": "Filings matching the filter across everything scanned; can exceed the inline list."
},
"fiscal_year_end": {
"type": "string",
"description": "Fiscal year end (MM-DD, e.g. \"09-26\"). Absent when SEC records none (e.g., private or pre-IPO entities)."
},
"sic_description": {
"type": "string",
"description": "Human-readable SIC description."
},
"state_of_incorporation": {
"type": "string",
"description": "State of incorporation (US two-letter code, e.g. \"DE\"). Absent for many foreign filers and individuals."
},
"history_scanned_through": {
"type": "string",
"description": "Oldest filing date the scan reached (YYYY-MM-DD); nothing older was examined. Archive pages past the recent window (last year or 1,000 filings) are read only for a date filter or an under-filled form filter. Absent when nothing was scanned."
}
},
"additionalProperties": false
}secedgar_company_search annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_search_filings — Secedgar Search Filings
Advertised read-onlyOpen-world
Search EDGAR filings since 1993. Full-text search covers 2001-present (the EFTS index floor); pre-2001 date ranges (to 1993) are served from the archives by form and entity/date. Pre-2001 free text needs entity scope (ticker:/cik:) — with it, the tool reads the entity's matching filings and matches the terms locally, which costs a few seconds (SEC's request rate caps the scan at roughly 5s for the 50-document maximum). A range crossing 2001-01-01 is split at the boundary and the two eras merged, each row tagged with its source. Supports exact phrases, boolean operators, wildcards, and entity targeting (ticker:AAPL or cik:320193 in query). When the match set outruns the inline list it is also staged as df_<id> — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.
secedgar_search_filings input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"sort": {
"enum": [
"filing_date_desc",
"filing_date_asc",
"relevance"
],
"type": "string",
"default": "filing_date_desc",
"description": "Result ordering. \"filing_date_desc\" (default) returns most recent first. \"filing_date_asc\" returns oldest first. \"relevance\" returns SEC's native search-score order, which weights term match strength over recency. Date sorts re-order the top 100 hits returned by the search index — for broad queries with more than 100 matches and no entity targeting, date-newest filings may sit outside that window. Entity targeting (ticker:/cik:) or a narrower query keeps matches inside the window when absolute recency matters. On the no-query browse path (forms/entity only), EFTS has no relevance signal — every hit scores null — and returns filings in natural date-descending order, so all sort modes effectively yield newest-first. Pre-2001 archive results carry no relevance score either, so relevance collapses to date-descending there."
},
"forms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter to specific form types (e.g., [\"10-K\", \"10-Q\", \"8-K\"]). Without this, searches all form types. Note: \"10-K\" also matches amendments filed as 10-K/A. SEC renamed the blockholder schedules on 2024-12-18 — filings before that date are \"SC 13D\"/\"SC 13G\", filings after are \"SCHEDULE 13D\"/\"SCHEDULE 13G\" — so a filter spanning that boundary must list both spellings. Ownership forms (3, 4, 5) are indexed by the reporting person (e.g., \"LEVINSON ARTHUR D\"), not the issuer — rows carry no transaction code, share count, or price. Use secedgar_get_insider_transactions to retrieve parsed ownership XML with person, relationship, transaction code, shares, and price."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 1000,
"minimum": 1,
"description": "Results per page. Capped at 100: a larger value, up to 1000, returns what 100 returns."
},
"query": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"minLength": 1,
"description": "Full-text search query. Supports: exact phrases (\"material weakness\"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), entity targeting (ticker:AAPL or cik:320193 in the query). Terms are AND'd by default."
}
],
"description": "Full-text search query. Optional — omit (or pass \"\") to browse by form type and/or entity instead, e.g. every S-1 in a date window, or a company's filings via ticker:/cik:. A date range alone is not a valid search; pair it with forms or entity targeting. The EFTS index that serves free text starts at 2001-01-01; a date range reaching earlier needs ticker:/cik: entity scope, which lets the tool read that entity's filings and match the terms locally (bounded to 50 documents, a few seconds at SEC's request rate), or drop the text terms and browse by form type (forms) and date. When present, supports exact phrases (\"material weakness\"), boolean operators (revenue OR income), exclusion (-preliminary), wildcard suffix (account*), and entity targeting (ticker:AAPL or cik:320193 in the query); terms are AND'd by default. A multi-class share ticker resolves in either form — ticker:BRK-B and ticker:BRK.B scope to the same issuer. The pre-2001 local scan honors the same phrase / OR / exclusion / wildcard syntax."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9999,
"minimum": 0,
"description": "Pagination offset. For sort=relevance on a 2001-onward search, EDGAR pages server-side, and the offset counts matching documents, not filings — EDGAR indexes each document of a filing separately — so a page lists the filings among its limit documents, which can be fewer than limit, and a filing whose matching documents straddle a page edge can recur on the next page; stepping by limit never skips one. EDGAR serves offsets up to 9900 there, where a page of limit 100 reaches its 10,000-document cap, and a deeper offset is rejected. Everywhere else the offset indexes the filings this call assembled and sorted: the filings of a single 100-document window for date sorts and entity targeting, the full matched set on a pre-2001 archive path, or both together on a range that crosses 2001-01-01. Offsets at or past those rows return nothing even when more filings match (a total above the rows fetched, or total_is_exact false) — switch to sort=relevance for deep pagination on a 2001-onward search, narrow the search (forms, dates, entity targeting), or query the dataframe. On a crossing range the two sides are assembled unevenly — the archive side contributes every row it matched, the full-text side the filings of one document window — so once the window runs out the rows jump to the pre-2001 era with the remaining full-text matches absent from the middle; search the 2001-onward era on its own to page through those."
},
"filed_after": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only include filings filed on or after this date (YYYY-MM-DD). Use alone or with filed_before; alone, the search runs through today (UTC)."
},
"filed_before": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; alone, the search starts at 2001-01-01, or at 1993-01-01 (the archive start) for a date before 2001."
}
},
"additionalProperties": false
}secedgar_search_filings output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"total",
"total_is_exact",
"results",
"effectiveQuery"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"scan": {
"type": "object",
"required": [
"candidates",
"scanned",
"matched",
"capped"
],
"properties": {
"capped": {
"type": "boolean",
"description": "True when candidates exceeded the 50-document cap; unread filings may match, so narrow forms or dates."
},
"matched": {
"type": "number",
"description": "Scanned filings whose text satisfied the query."
},
"scanned": {
"type": "number",
"description": "Candidates fetched and matched, at most 50 per call."
},
"candidates": {
"type": "number",
"description": "Filings the form and date pre-filter selected."
}
},
"description": "Pre-2001 entity-scoped free-text path only. Each candidate's whole accession .txt is read, so a match may sit in an exhibit rather than the body of the requested form.",
"additionalProperties": false
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"unresolved_ticker",
"ambiguous_company",
"invalid_cik",
"entity_not_found",
"missing_criteria",
"pre2001_full_text_unscoped",
"offset_out_of_range",
"rate_limited",
"sec_unreachable",
"efts_degraded_response"
],
"description": "Machine-readable failure mode. Declared by this tool: `unresolved_ticker`: A ticker: targeting token in the query does not resolve to a known company. `ambiguous_company`: A ticker: targeting token in the query resolves to multiple companies and the target is ambiguous. `invalid_cik`: A cik: targeting token in the query is not a 1-10 digit number. `entity_not_found`: A cik: targeting token on a pre-2001 date range names a CIK with no EDGAR submissions history. `missing_criteria`: Neither a full-text query nor a forms filter was provided (a date range cannot stand alone). `pre2001_full_text_unscoped`: A date range reaching before 2001-01-01 carries free-text terms with no entity scope — no pre-2001 full-text index exists, and nothing bounds a local scan. `offset_out_of_range`: A sort=relevance search with no ticker:/cik: scope and no date range reaching before 2001 asks for an offset above 9900, past the deepest page EDGAR full-text search serves. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. `efts_degraded_response`: EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of results shown inline."
},
"total": {
"type": "number",
"description": "Matching filings, one per accession; can exceed the rows returned. A search with terms counts the filings among the full-text documents fetched (100 per request): a lower bound unless total_is_exact. A forms- or entity-only browse from 2001 on gives EDGAR's own count; earlier ranges count rows read."
},
"notice": {
"type": "string",
"description": "Why nothing matched, what lies past a truncated list and how to reach it, or that offset passed the filings available."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"truncated": {
"type": "boolean",
"description": "True when matches exist beyond the staged rows: the full-text window was exceeded, or an archive scan hit its cap."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of every filing assembled (the full-text window, or the full pre-2001 match set). Absent when the rows fit inline, canvas is unavailable, or staging failed.",
"additionalProperties": false
},
"results": {
"type": "array",
"items": {
"type": "object",
"required": [
"accession_number",
"filing_date",
"company_name",
"cik"
],
"properties": {
"cik": {
"type": "string",
"description": "Filing entity CIK, zero-padded to 10 digits."
},
"sic": {
"type": "string",
"description": "SIC industry code. Absent for filers without one."
},
"form": {
"type": "string",
"description": "Form type (e.g. \"10-K\"). Absent for hits where the index lacks a form tag."
},
"source": {
"enum": [
"efts",
"submissions",
"full-index"
],
"type": "string",
"description": "\"efts\" (2001+ full-text), \"submissions\" (pre-2001 entity history), or \"full-index\" (pre-2001 quarterly index). A range crossing 2001-01-01 mixes sources; total sums its archive rows and the filings of one 100-document full-text window. Also a dataframe column."
},
"ticker": {
"type": "string",
"description": "Primary ticker; the first class for multi-class issuers (BRK-A / BRK-B). Absent for private filers, foreign filers without a US listing, and display names that omit it."
},
"location": {
"type": "string",
"description": "Business location (state or country code). Absent when SEC has none."
},
"filing_date": {
"type": "string",
"description": "Date the filing was submitted (YYYY-MM-DD)."
},
"company_name": {
"type": "string",
"description": "Filing entity, with ticker/CIK parentheticals stripped."
},
"period_ending": {
"type": "string",
"description": "Period the filing reports on (YYYY-MM-DD). Absent for forms without one (proxy statements, ownership reports)."
},
"accession_number": {
"type": "string",
"description": "Accession number for secedgar_get_filing."
},
"file_description": {
"type": "string",
"description": "SEC description of the first-ranked matching document (e.g., \"EX-99.1\"). Absent when SEC published none."
},
"matched_documents": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"name": {
"type": "string",
"description": "Document filename — pass as secedgar_get_filing document to read it."
},
"type": {
"type": "string",
"description": "EDGAR document type (e.g., \"EX-99.1\"), telling body from exhibit. Absent when the index has none."
}
},
"description": "One document of this filing that matched the query.",
"additionalProperties": false
},
"description": "Documents of this filing that matched, in rank order; the dataframe holds their filenames as a comma-separated column."
}
},
"description": "One matching filing. period_ending, ticker, file_description, matched_documents, sic, and location are absent on pre-2001 archive rows (source submissions or full-index).",
"additionalProperties": false
},
"description": "Matching filings."
},
"truncated": {
"type": "boolean",
"description": "True when more filings match than are shown: limit capped the list, or total is a lower bound."
},
"effectiveQuery": {
"type": "string",
"description": "The query as executed: \"(entity scope: CIK …)\" for a ticker:/cik: token, \"(browse: forms …)\" for a forms-only browse, a pre-2001 range's archive route and dates (and quarters read, if the full-index cap bound), and \"(filed <after> to <before>)\" for a full-text search given one bound."
},
"total_is_exact": {
"type": "boolean",
"description": "False when total is a lower bound: a search with terms whose 100-document window missed matches (or a relevance page past offset 0), EDGAR's 10,000 cap, or a pre-2001 archive or text scan that hit its cap. True does not mean every match is in the rows: a browse total can exceed the window."
},
"total_documents": {
"type": "number",
"description": "EDGAR's count of matching full-text documents, capped at 10,000. A search counts a filing once per matching document; a browse matches one document per filing. Absent on pure pre-2001 archive paths."
},
"form_distribution": {
"type": "object",
"description": "Filings in hand by form: every row assembled (what a dataframe holds), not only the page shown. Sums to total when every matching filing is in hand and every row has a form.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
}
},
"additionalProperties": false
}secedgar_search_filings annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_filing — Secedgar Get Filing
Advertised read-onlyOpen-world
Fetch a specific filing's metadata and document content by accession number. Returns the primary document as readable text. Use offset/next_offset for multi-page access to large filings (10-K, S-1 can exceed 1M chars): pass the next_offset from a truncated response as offset, without section, to read the next page. Use section to jump directly to a heading (e.g. 'risk factors', 'item 7') without needing an offset.
secedgar_get_filing input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"accession_number"
],
"properties": {
"cik": {
"type": "string",
"pattern": "^\\d{1,10}$",
"description": "Filer CIK, digits only (resolve via secedgar_company_search if you have a ticker or name). Optional but recommended — speeds up archive lookup. If omitted, the filer is looked up from the accession number through EDGAR full-text search (2001 onward) and the accession number's own prefix, which for many filings is a filing agent's CIK, and when none of those directories serves the filing, through the filers its index page names."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Character offset into the extracted document text. Pass next_offset from a truncated response to continue reading the next page, and leave section out: section takes precedence over offset. Default 0 reads from the beginning."
},
"section": {
"type": "string",
"minLength": 1,
"description": "Jump to a named section, matched against every detected heading and the document's own lines (e.g. 'risk factors', 'item 7', 'item 2.02', 'certain relationships'). The first match wins, in this order: a heading equal to the value, or whose title after its Item/Part marker equals it; the first Item or Part heading containing it; a document line equal to it — a subheading the outline omits ('Liquidity and Capital Resources') — unless the line labels a table row; the first other heading containing it; a table-row label equal to it, else a document line starting with it. In a proxy statement (DEF 14A and its variants), whose ITEM headings are ballot proposals, the first heading of any kind containing the value comes before both document-line steps. Within each heading step a body heading wins over a table-of-contents row, which lands only when nothing else at that step matches. A line landing says so in the notice; table-of-contents rows and wrapped cross-references are never line landings. A leading 20-F sub-item label on a heading or line ('3D.', 'B.') is ignored, so 'risk factors' reaches '3D. RISK FACTORS'; the value itself is matched as given. A value ending in a number matches only that number: 'item 1' reaches Item 1 and Item 1A, never Items 10–16, and 'part i' never reaches Part II. Every step ignores case, whitespace, and quote style, so a heading copied from the outline resolves whether it carries the filing's non-breaking spaces and curly quotes or plain ones; the steps comparing a whole heading or line (equal to, starting with) also ignore the punctuation between an Item or Part marker and its title, so 'Item 1A Risk Factors' reaches 'Item 1A. – Risk Factors'. Takes precedence over offset when both are provided, so leave it out when paging on with next_offset. On a miss, the error message includes the detected outline so you can pick the correct heading."
},
"document": {
"type": "string",
"description": "Specific document filename within the filing (e.g., \"ex-21.htm\" for subsidiaries list). Omitted or blank: the primary document. Available documents are listed in the response metadata under documents, and a primary_document value is accepted too; entries marked binary hold no text and are rejected."
},
"include_xbrl": {
"type": "boolean",
"default": false,
"description": "Include XBRL viewer artifacts and machine-readable taxonomy files (R*.htm fragments, *_cal/_def/_lab/_pre.xml linkbases, *_htm.xml inline instance, *.xsd schemas, MetaLinks.json, FilingSummary.xml, Show.js, report.css, *-xbrl.zip, Financial_Report.xlsx, EX-101.* technical exhibits) under documents.xbrl. Off by default — these dominate filing indexes (~100 entries on a typical 10-K) and are rarely relevant when reading filing content."
},
"content_limit": {
"type": "integer",
"default": 50000,
"maximum": 1000000,
"minimum": 1000,
"description": "Maximum characters of document text to return per page. 10-K filings can exceed 500,000 characters; S-1/A can exceed 1,000,000. Default 50,000 captures ~12,000 words (typically business overview, risk factors, and MD&A). Increase to 200,000 for full financial statements, or decrease for quick summaries. Use offset or section for subsequent pages. Capped at 200000: a larger value, up to 1000000, returns what 200000 returns."
},
"accession_number": {
"type": "string",
"pattern": "^(?:\\d{10}-\\d{2}-\\d{6}|\\d{18})$",
"description": "Filing accession number in either format: \"0000320193-23-000106\" (dashes) or \"000032019323000106\" (no dashes). Obtained from secedgar_company_search or secedgar_search_filings results."
}
},
"additionalProperties": false
}secedgar_get_filing output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"accession_number",
"cik",
"primary_document",
"documents",
"content",
"content_truncated",
"content_total_length",
"filing_url"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The `content_limit` that was applied."
},
"cik": {
"type": "string",
"description": "Filing entity CIK, zero-padded to 10 digits."
},
"form": {
"type": "string",
"description": "Form type (e.g., \"10-K\"), from the submissions feed or the filing's SEC header. Absent only when neither has it."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"document_not_found",
"no_documents",
"binary_document",
"filing_not_found",
"offset_out_of_range",
"section_not_found",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `document_not_found`: A specific document was requested but not present in the filing archive. `no_documents`: Filing index lists items but no fetchable primary document was found. `binary_document`: The requested document is a binary entry (scanned image, PDF, archive) with no text to return. `filing_not_found`: No filing matches the accession number under any candidate CIK. `offset_out_of_range`: The provided offset is at or beyond the end of the document. `section_not_found`: The section string matched no detected heading and no line of the document. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Characters of document text returned on this page."
},
"notice": {
"type": "string",
"description": "How to read the next page, which file was read when the archive does not serve the indexed primary, when section landed on a document line rather than a detected heading, and how many headings were detected when the outline lists fewer."
},
"content": {
"type": "string",
"description": "Document text content for this page window."
},
"outline": {
"type": "array",
"items": {
"type": "object",
"required": [
"heading",
"offset"
],
"properties": {
"offset": {
"type": "number",
"description": "Character offset of this heading in the full document; pass as offset."
},
"heading": {
"type": "string",
"description": "Detected heading text."
}
},
"description": "One detected heading with its offset.",
"additionalProperties": false
},
"description": "Up to 50 detected headings, on the first page of a truncated response (offset=0, no section). Past 50, Item and Part headings come first (bare TOC copies of titled ones dropped), then the earliest others; the notice gives the detected count. Pass a heading offset as offset, or its text as section."
},
"documents": {
"type": "object",
"required": [
"primary",
"exhibits",
"auxiliary"
],
"properties": {
"xbrl": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Document filename within the filing archive."
},
"size": {
"type": "number",
"description": "File size in bytes."
},
"type": {
"type": "string",
"description": "SEC document type (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\"), or without a submission header a filename-inferred label (\"exhibit\", \"PDF\", \"unknown\")."
},
"binary": {
"type": "boolean",
"description": "True for a binary entry (scan, PDF, archive, spreadsheet); absent otherwise."
},
"description": {
"type": "string",
"description": "SEC description (e.g., \"Subsidiaries of the Registrant\"). Absent when none."
}
},
"description": "One document entry from the filing.",
"additionalProperties": false
},
"description": "XBRL viewer artifacts and taxonomy files. Present only when include_xbrl=true."
},
"primary": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Document filename within the filing archive."
},
"size": {
"type": "number",
"description": "File size in bytes."
},
"type": {
"type": "string",
"description": "SEC document type (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\"), or without a submission header a filename-inferred label (\"exhibit\", \"PDF\", \"unknown\")."
},
"binary": {
"type": "boolean",
"description": "True for a binary entry (scan, PDF, archive, spreadsheet); absent otherwise."
},
"description": {
"type": "string",
"description": "SEC description (e.g., \"Subsidiaries of the Registrant\"). Absent when none."
}
},
"description": "One document entry from the filing.",
"additionalProperties": false
},
"description": "Primary document(s), typically one entry whose type matches the form."
},
"exhibits": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Document filename within the filing archive."
},
"size": {
"type": "number",
"description": "File size in bytes."
},
"type": {
"type": "string",
"description": "SEC document type (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\"), or without a submission header a filename-inferred label (\"exhibit\", \"PDF\", \"unknown\")."
},
"binary": {
"type": "boolean",
"description": "True for a binary entry (scan, PDF, archive, spreadsheet); absent otherwise."
},
"description": {
"type": "string",
"description": "SEC description (e.g., \"Subsidiaries of the Registrant\"). Absent when none."
}
},
"description": "One document entry from the filing.",
"additionalProperties": false
},
"description": "Filed exhibits (EX-21, EX-31/32, EX-99, etc.), excluding XBRL EX-101.*; without a submission header, matched by filename (type \"exhibit\"), the rest under auxiliary."
},
"auxiliary": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type"
],
"properties": {
"name": {
"type": "string",
"description": "Document filename within the filing archive."
},
"size": {
"type": "number",
"description": "File size in bytes."
},
"type": {
"type": "string",
"description": "SEC document type (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\"), or without a submission header a filename-inferred label (\"exhibit\", \"PDF\", \"unknown\")."
},
"binary": {
"type": "boolean",
"description": "True for a binary entry (scan, PDF, archive, spreadsheet); absent otherwise."
},
"description": {
"type": "string",
"description": "SEC description (e.g., \"Subsidiaries of the Registrant\"). Absent when none."
}
},
"description": "One document entry from the filing.",
"additionalProperties": false
},
"description": "Other supporting documents: cover pages, consent letters, graphics."
}
},
"description": "Filing documents by category. Any name is a valid document input except entries with binary: true, which fail with binary_document; scans can outnumber readable documents.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when the document is longer than `content_limit` allowed through."
},
"filing_url": {
"type": "string",
"description": "Direct URL to the filing on SEC.gov."
},
"filing_date": {
"type": "string",
"description": "Date the filing was submitted (YYYY-MM-DD). Absent under the same conditions as form."
},
"next_offset": {
"type": "number",
"description": "Offset of the next page, to pass as offset without section; present while content_truncated is true."
},
"company_name": {
"type": "string",
"description": "Filing entity name. Absent if the CIK did not resolve to a known entity."
},
"period_ending": {
"type": "string",
"description": "Period of report (YYYY-MM-DD), from the same source as form. Absent for forms without one (S-8, Form 4, proxy statements) or when neither source has it."
},
"accession_number": {
"type": "string",
"description": "Filing accession number, normalized to dash format."
},
"primary_document": {
"type": "string",
"description": "Primary document as read: an XML form's SEC rendering (xsl…/form4.xml) up to 600 KB raw; a 2000–2001 name SEC does not serve, as <accession>-<name>, else the full submission <accession>.txt."
},
"content_truncated": {
"type": "boolean",
"description": "True if content was truncated at content_limit."
},
"requested_document": {
"type": "string",
"description": "Filename requested via document. Present only when it differs from primary_document."
},
"content_total_length": {
"type": "number",
"description": "Full document length in characters."
}
},
"additionalProperties": false
}secedgar_get_filing annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_financials — Secedgar Get Financials
Advertised read-onlyOpen-world
Get historical XBRL financial data for a company. Accepts friendly concept names (e.g., "revenue", "net_income", "assets") or raw XBRL tags. Discover available friendly names with secedgar_search_concepts. Handles historical tag changes and deduplicates data automatically. The full series is also staged as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.
secedgar_get_financials input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"company",
"concept"
],
"properties": {
"unit": {
"type": "string",
"minLength": 1,
"description": "SEC unit key to read the series in, for a concept reported in more than one (e.g. \"ZAR\" and a \"USD\" convenience translation, or \"USD/EUR\" among exchange-rate pairs). \"USD-per-shares\" is read as \"USD/shares\". When omitted, the series takes the unit of its newest value, then the unit with more periods; any other units are named in caveats."
},
"limit": {
"type": "integer",
"maximum": 100,
"minimum": 1,
"description": "Cap the inline data[] to the most-recent N periods (the series is newest-first). The full series is always registered to the dataframe, so older periods stay queryable via secedgar_dataframe_query. Omit to return every period inline."
},
"company": {
"type": "string",
"minLength": 1,
"description": "Ticker symbol (e.g., \"AAPL\") or CIK number. Ticker is preferred."
},
"concept": {
"type": "string",
"minLength": 1,
"description": "Financial concept — friendly name (e.g., \"revenue\", \"net_income\", \"assets\", \"eps_diluted\") or raw XBRL tag (e.g., \"AccountsPayableCurrent\"). Friendly names auto-resolve to the correct XBRL tags and handle historical tag changes."
},
"taxonomy": {
"enum": [
"us-gaap",
"ifrs-full",
"dei"
],
"type": "string",
"default": "us-gaap",
"description": "XBRL taxonomy. us-gaap for US companies, ifrs-full for foreign filers, dei for entity info (shares outstanding)."
},
"period_type": {
"enum": [
"annual",
"quarterly",
"all"
],
"type": "string",
"description": "Filter to annual (FY) or quarterly (Q1-Q4) data. \"all\" returns both. For an instant (balance-sheet) concept, \"annual\" returns the values dated on the filer's fiscal-year ends. When omitted, defaults to \"annual\", except that an instant concept returns its full series."
}
},
"additionalProperties": false
}secedgar_get_financials output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"company",
"cik",
"concept",
"label",
"unit",
"data"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"cik": {
"type": "string",
"description": "Resolved CIK, zero-padded to 10 digits."
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"period",
"value",
"end",
"fiscal_year",
"fiscal_period",
"form",
"filed",
"accession_number",
"tag"
],
"properties": {
"end": {
"type": "string",
"description": "Period end date (YYYY-MM-DD)."
},
"tag": {
"type": "string",
"description": "XBRL tag this value was reported under; differs from concept when an older or successor tag answers this period."
},
"form": {
"type": "string",
"description": "Source filing type (10-K, 10-Q, etc.)."
},
"filed": {
"type": "string",
"description": "Date the source filing was submitted (YYYY-MM-DD)."
},
"start": {
"type": "string",
"description": "Period start date (YYYY-MM-DD). Duration items only."
},
"value": {
"type": "number",
"description": "Reported value."
},
"period": {
"type": "string",
"description": "Calendar period label (e.g., \"CY2023\", \"CY2023Q3\")."
},
"fiscal_year": {
"type": [
"number",
"null"
],
"description": "Fiscal year of the source filing, not of the data period (restated comparatives carry the filing's year); key time on end. Null when not encoded."
},
"fiscal_period": {
"type": [
"string",
"null"
],
"description": "Fiscal period of the source filing (FY, Q1–Q4), not of the data period. Null when not encoded."
},
"accession_number": {
"type": "string",
"description": "Source filing accession number for secedgar_get_filing."
}
},
"description": "One reported value with its period, source filing, and tag.",
"additionalProperties": false
},
"description": "Deduplicated series, newest first, one value per calendar period. A proxy-framed period takes the filer's own report; an annual frame held by a 10-Q trailing-twelve-month figure is left out. An instant's annual values are its fiscal-year-end values (CY2025Q2I for a June year end)."
},
"unit": {
"type": "string",
"description": "Unit of every value in data (e.g., \"USD\", \"USD/shares\"): the unit input when given (an unreported one fails with no_unit_data), else the newest value's unit, then the unit with more periods. A series never mixes units."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"company_not_found",
"ambiguous_company",
"unknown_concept",
"no_concept_data",
"no_frame_data",
"no_period_data",
"no_unit_data",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `unknown_concept`: The concept input is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `no_concept_data`: The company does not report any XBRL data for the resolved concept and taxonomy. `no_frame_data`: Concept exists but has no frame-aligned (standard calendar period) entries. `no_period_data`: Concept has data but the period_type filter excluded all of it — under \"annual\", an instant concept with no value dated on a fiscal-year end. `no_unit_data`: The unit input names a unit the resolved concept is not reported in for this company. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"label": {
"type": "string",
"description": "Human-readable taxonomy label of the concept tag."
},
"shown": {
"type": "number",
"description": "Number of periods shown inline."
},
"notice": {
"type": "string",
"description": "Guidance when the inline series was capped, or when the full series is staged as a dataframe."
},
"caveats": {
"type": "array",
"items": {
"type": "string"
},
"description": "Completeness warnings, absent when none apply: other units the concept is reported in, with period counts and spans (pass unit to read one); quarters missing from every recent year (SEC reports fiscal Q4 only within the 10-K); a series ending well short of today (a retired or dropped tag)."
},
"company": {
"type": "string",
"description": "Resolved entity name (SEC-conformed)."
},
"concept": {
"type": "string",
"description": "XBRL tag behind the newest value; each row names its own tag."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of the same series; fiscal keys are source_filing_fy/source_filing_fp, so order by period_end. Absent when canvas is unavailable.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when the inline data[] was capped by limit."
},
"tags_tried": {
"type": "array",
"items": {
"type": "string"
},
"description": "XBRL tags attempted, when a friendly name maps to several."
},
"description": {
"type": "string",
"description": "XBRL taxonomy description of the tag. Often absent for extension tags and older concepts."
}
},
"additionalProperties": false
}secedgar_get_financials annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_snapshot — Secedgar Get Snapshot
Advertised read-onlyOpen-world
Build a company financial profile in one call: the latest value of every supported XBRL concept, grouped by statement. Reads the filer's complete companyfacts payload once rather than one request per concept, so it replaces a run of secedgar_get_financials calls when the question is "what do this company's financials look like right now". Values use the same frame dedup and tag priority as secedgar_get_financials, so the two agree for any concept they both cover. Duration concepts (income statement, cash flow, per-share) report their latest full year and latest single quarter; balance-sheet and entity-info concepts report their latest point-in-time value, since that is the only form they are filed in. A concept the filer does not report is listed under gaps with the XBRL tags that were tried — never zero-filled or interpolated. Use secedgar_get_financials for a full time series of one concept, and secedgar_compare_companies to put several companies side by side.
secedgar_get_snapshot input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"company"
],
"properties": {
"company": {
"type": "string",
"minLength": 1,
"description": "Ticker symbol (e.g. \"AAPL\") or CIK number. Ticker is preferred."
},
"taxonomy": {
"enum": [
"us-gaap",
"ifrs-full"
],
"type": "string",
"default": "us-gaap",
"description": "XBRL taxonomy to resolve concepts under. Every concept is looked up in this one taxonomy, so ifrs-full covers only the concepts with confirmed IFRS tag variants and the rest — including the dei entity-info concepts — come back under gaps. Leave at us-gaap for domestic filers, where each concept uses its own preferred taxonomy."
},
"period_type": {
"enum": [
"annual",
"quarterly",
"both"
],
"type": "string",
"default": "both",
"description": "Which duration periods to report per concept: the latest full year, the latest single quarter, or both (default). Balance-sheet and entity-info concepts are point-in-time and always report their latest instant value regardless of this setting."
}
},
"additionalProperties": false
}secedgar_get_snapshot output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"company",
"cik",
"taxonomy",
"period_type",
"concepts_resolved",
"concepts_total",
"lines",
"gaps",
"caveats"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cik": {
"type": "string",
"description": "Resolved CIK, zero-padded to 10 digits."
},
"gaps": {
"type": "array",
"items": {
"type": "object",
"required": [
"concept",
"label",
"group",
"tags_tried"
],
"properties": {
"group": {
"type": "string",
"description": "Statement group the concept belongs to."
},
"label": {
"type": "string",
"description": "Human-readable concept label."
},
"concept": {
"type": "string",
"description": "Friendly concept name that produced no value."
},
"tags_tried": {
"type": "array",
"items": {
"type": "string"
},
"description": "XBRL tags attempted, in priority order, before giving up."
}
},
"description": "One concept the filer does not report.",
"additionalProperties": false
},
"description": "Concepts with no value for this filer, never zero-filled or interpolated."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"company_not_found",
"ambiguous_company",
"no_company_facts",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a CIK. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_company_facts`: The filer has no XBRL facts at all — pre-XBRL, foreign private issuer, or a non-operating registrant. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"lines": {
"type": "array",
"items": {
"type": "object",
"required": [
"concept",
"label",
"group",
"taxonomy",
"tag",
"unit"
],
"properties": {
"tag": {
"type": "string",
"description": "XBRL tag behind the newest value; each point names its own."
},
"unit": {
"type": "string",
"description": "Unit of every point on the line (e.g., \"USD\"). A concept in several units reads its newest value's unit, then the one with more periods; secedgar_get_financials reads the others."
},
"group": {
"type": "string",
"description": "Statement group: income_statement, balance_sheet, cash_flow, per_share, or entity_info."
},
"label": {
"type": "string",
"description": "Human-readable concept label."
},
"annual": {
"type": "object",
"required": [
"period",
"value",
"period_end",
"form",
"accession_number",
"tag"
],
"properties": {
"tag": {
"type": "string",
"description": "XBRL tag behind this value; can differ from the line's tag."
},
"form": {
"type": "string",
"description": "Source filing type (10-K, 10-Q, 20-F)."
},
"value": {
"type": "number",
"description": "Reported value, in the line's unit."
},
"period": {
"type": "string",
"description": "Calendar period label (e.g. \"CY2024\", \"CY2025Q2\", \"CY2025Q2I\")."
},
"period_end": {
"type": "string",
"description": "Period end date (YYYY-MM-DD)."
},
"accession_number": {
"type": "string",
"description": "Source filing accession number for secedgar_get_filing."
}
},
"description": "Latest full-year (CY####) value.",
"additionalProperties": false
},
"concept": {
"type": "string",
"description": "Friendly concept name (e.g. \"revenue\")."
},
"instant": {
"type": "object",
"required": [
"period",
"value",
"period_end",
"form",
"accession_number",
"tag"
],
"properties": {
"tag": {
"type": "string",
"description": "XBRL tag behind this value; can differ from the line's tag."
},
"form": {
"type": "string",
"description": "Source filing type (10-K, 10-Q, 20-F)."
},
"value": {
"type": "number",
"description": "Reported value, in the line's unit."
},
"period": {
"type": "string",
"description": "Calendar period label (e.g. \"CY2024\", \"CY2025Q2\", \"CY2025Q2I\")."
},
"period_end": {
"type": "string",
"description": "Period end date (YYYY-MM-DD)."
},
"accession_number": {
"type": "string",
"description": "Source filing accession number for secedgar_get_filing."
}
},
"description": "Latest point-in-time (CY####Q#I) value.",
"additionalProperties": false
},
"taxonomy": {
"type": "string",
"description": "Taxonomy the value was read from."
},
"quarterly": {
"type": "object",
"required": [
"period",
"value",
"period_end",
"form",
"accession_number",
"tag"
],
"properties": {
"tag": {
"type": "string",
"description": "XBRL tag behind this value; can differ from the line's tag."
},
"form": {
"type": "string",
"description": "Source filing type (10-K, 10-Q, 20-F)."
},
"value": {
"type": "number",
"description": "Reported value, in the line's unit."
},
"period": {
"type": "string",
"description": "Calendar period label (e.g. \"CY2024\", \"CY2025Q2\", \"CY2025Q2I\")."
},
"period_end": {
"type": "string",
"description": "Period end date (YYYY-MM-DD)."
},
"accession_number": {
"type": "string",
"description": "Source filing accession number for secedgar_get_filing."
}
},
"description": "Latest single-quarter (CY####Q#) value.",
"additionalProperties": false
}
},
"description": "One concept with its latest values: duration concepts carry annual and quarterly as period_type allows; point-in-time concepts carry instant only.",
"additionalProperties": false
},
"description": "Resolved concepts, ordered by statement group then concept name."
},
"caveats": {
"type": "array",
"items": {
"type": "string"
},
"description": "Completeness warnings, else empty: quarters missing from every recent year (SEC reports fiscal Q4 only within the 10-K), and, prefixed with the concept name, lines stopping 2+ years behind the filer's newest period."
},
"company": {
"type": "string",
"description": "Resolved entity name (SEC-conformed)."
},
"taxonomy": {
"type": "string",
"description": "Taxonomy the concepts were resolved under, echoed from input."
},
"period_type": {
"type": "string",
"description": "Duration periods reported, echoed from input."
},
"concepts_total": {
"type": "number",
"description": "Concepts in the supported catalog that were attempted."
},
"concepts_resolved": {
"type": "number",
"description": "Concepts that produced at least one value."
}
},
"additionalProperties": false
}secedgar_get_snapshot annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_material_events — Get Material Events
Advertised read-onlyOpen-world
Retrieve a company's 8-K filings with their item codes decoded, optionally filtered to specific items. 8-K item codes are how material events are actually scoped — 1.01 material agreements, 2.02 results of operations, 4.02 non-reliance on previously issued financials, 5.02 officer and director departures — and filtering by them is narrower than any form-level filter in secedgar_search_filings or secedgar_company_search, neither of which can see items. Each row carries the accession number and primary document for secedgar_get_filing; press releases usually ride as EX-99 exhibits rather than in the primary document. Two numbering regimes exist: filings from 2004-08-23 onward use the x.xx codes, earlier ones use single integers (12 was the old results-of-operations item, 9 the old Regulation FD item), and both are accepted as filters and decoded in the response. A date window reaches filings older than the recent submissions window by reading every archive page it overlaps, up to 10; without one, the scan reads back only as far as it needs to fill limit with filings passing the items filter, within the same 10 pages. Every scanned filing that passes the filter is materialized as df_<id> for item-distribution analysis over time (pass a date window to cover a longer span) — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.
secedgar_get_material_events input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"company"
],
"properties": {
"items": {
"type": "array",
"items": {
"enum": [
"1",
"2",
"3",
"4",
"5",
"6",
"7",
"8",
"9",
"10",
"11",
"12",
"1.01",
"1.02",
"1.03",
"1.04",
"1.05",
"2.01",
"2.02",
"2.03",
"2.04",
"2.05",
"2.06",
"3.01",
"3.02",
"3.03",
"4.01",
"4.02",
"5.01",
"5.02",
"5.03",
"5.04",
"5.05",
"5.06",
"5.07",
"5.08",
"6.01",
"6.02",
"6.03",
"6.04",
"6.05",
"6.06",
"7.01",
"8.01",
"9.01"
],
"type": "string"
},
"maxItems": 20,
"description": "Item codes to filter to; a filing matches when it reports any of them. Omit to return every 8-K. Current-regime codes are dotted (\"2.02\"), pre-2004-08-23 codes are bare integers (\"12\"), and the two vocabularies do not overlap — filtering on \"2.02\" alone returns nothing from a pre-2004 window, so pair them (\"2.02\", \"12\") when the window spans the changeover. Full decode table: the secedgar://filing-types resource."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 1000,
"minimum": 1,
"description": "Filings returned inline, newest first. Every scanned filing that passes the filter is materialized as a dataframe when there are more than this and a canvas is available. Default 20. Capped at 100: a larger value, up to 1000, returns what 100 returns."
},
"company": {
"type": "string",
"minLength": 1,
"description": "Company ticker symbol (e.g. \"AAPL\"), name (e.g. \"Apple\"), or CIK number (e.g. \"320193\"). Ticker is the exact lookup; name search matches current and former names."
},
"filed_after": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only include filings filed on or after this date (YYYY-MM-DD). A date filter routes the scan into the older submissions archive pages, so it reaches 8-K filings that predate the recent window (the last year or 1,000 filings of every form, whichever holds more)."
},
"filed_before": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only include filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after; together they bound the archive-page scan."
}
},
"additionalProperties": false
}secedgar_get_material_events output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"cik",
"company_name",
"total_matched",
"total_8k_scanned",
"item_distribution",
"filings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"cik": {
"type": "string",
"description": "Resolved CIK, zero-padded to 10 digits."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"no_match",
"ambiguous_company",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `no_match`: No company matches the query. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of filings shown inline."
},
"notice": {
"type": "string",
"description": "Why nothing matched (an empty date window, or an items filter that excluded everything), and, when fewer than limit matched while the page cap left pages unread, how far the scan reached and the window that goes further."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"truncated": {
"type": "boolean",
"description": "True when archive pages in range went unread (the 10-page cap, or an undated call that stopped once limit was filled, possibly before any archive page), so older matches may exist. Pass filed_after / filed_before to reach them."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of every scanned 8-K passing the filter; item_codes is comma-separated (unnest(string_split(item_codes, ','))). Absent when the result fits inline, canvas is unavailable, or staging failed.",
"additionalProperties": false
},
"filings": {
"type": "array",
"items": {
"type": "object",
"required": [
"accession_number",
"form",
"filing_date",
"items"
],
"properties": {
"form": {
"type": "string",
"description": "Form type — \"8-K\", or \"8-K/A\" for an amendment."
},
"items": {
"type": "array",
"items": {
"type": "object",
"required": [
"code"
],
"properties": {
"code": {
"type": "string",
"description": "Item code exactly as EDGAR reported it."
},
"label": {
"type": "string",
"description": "Item title from Form 8-K. Absent for a code neither numbering regime defines."
},
"regime": {
"enum": [
"current",
"legacy"
],
"type": "string",
"description": "\"current\" (dotted, since 2004-08-23) or \"legacy\" (single integer, before). Absent for an unrecognized code."
}
},
"description": "One reported 8-K item.",
"additionalProperties": false
},
"description": "Items this filing reports, decoded. Empty when EDGAR records none (some older filings)."
},
"description": {
"type": "string",
"description": "SEC-provided filing description. Absent when SEC published none."
},
"filing_date": {
"type": "string",
"description": "Date the filing was submitted (YYYY-MM-DD)."
},
"report_date": {
"type": "string",
"description": "Date of the reported event (YYYY-MM-DD), usually before filing_date. Absent when SEC records none."
},
"accession_number": {
"type": "string",
"description": "Accession number, dash format, for secedgar_get_filing."
},
"primary_document": {
"type": "string",
"description": "Primary document filename for secedgar_get_filing; press releases are usually EX-99 exhibits. Absent on older filings, which resolve from the accession number alone."
}
},
"description": "One 8-K filing.",
"additionalProperties": false
},
"description": "Matching filings, newest first, capped at limit."
},
"truncated": {
"type": "boolean",
"description": "True when the inline filings list was capped."
},
"company_name": {
"type": "string",
"description": "SEC-conformed company name."
},
"items_filter": {
"type": "array",
"items": {
"type": "string"
},
"description": "The item codes filtered on, echoed. Absent when no filter was applied."
},
"total_matched": {
"type": "number",
"description": "Filings matching every filter across the scan; can exceed limit."
},
"total_8k_scanned": {
"type": "number",
"description": "8-K filings in the date window before the items filter; compare total_matched."
},
"item_distribution": {
"type": "object",
"description": "Scanned 8-K filings per item code, before the items filter. Empty when none were scanned.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": "number"
}
},
"history_scanned_through": {
"type": "string",
"description": "Oldest filing date the scan reached (YYYY-MM-DD); nothing older was examined. The scan reads the recent window (last year or 1,000 filings), then up to 10 archive pages: those a date filter overlaps, or, undated, until limit filings pass the items filter. Absent when nothing was scanned."
}
},
"additionalProperties": false
}secedgar_get_material_events annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_insider_transactions — Get Insider Transactions
Advertised read-onlyOpen-world
Fetch Form 4 insider transactions (purchases, sales, grants, exercises) for a company by parsing SEC EDGAR ownership XML. Returns the reporting person, their relationship to the issuer, transaction date, type, shares traded (absolute magnitude), direction (acquire/dispose), price per share, and shares owned after the transaction. Covers nonDerivative transactions (open-market buys/sells, gifts) and derivative transactions (option exercises, RSU vests). Without a date window it reads the newest Form 4 filings; filed_after / filed_before read any period since mid-2003, reaching past the recent submissions window into the archive (e.g. insider trades in the quarter before an earnings miss). When a canvas is available, the full set of transactions parsed from the scanned filings is materialized as df_<id> (the inline list is a preview capped at limit) — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query to aggregate net buy/sell by insider: SUM(CASE WHEN direction='dispose' THEN -shares_traded ELSE shares_traded END). Use secedgar_search_filings with forms=["4"] to search Form 4 filings across all companies.
secedgar_get_insider_transactions input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"company"
],
"properties": {
"limit": {
"type": "integer",
"default": 20,
"maximum": 1000,
"minimum": 1,
"description": "Maximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20. Capped at 100: a larger value, up to 1000, returns what 100 returns."
},
"company": {
"type": "string",
"minLength": 1,
"description": "The issuer whose Form 4 filings to read — the company, not the reporting person. A ticker symbol (e.g., \"AAPL\"), a CIK with or without zero-padding (e.g., \"320193\" or \"0000320193\"), or a company name (current or former). A name matching several companies fails and lists them, so retry with one's ticker or CIK."
},
"filed_after": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only read Form 4 filings filed on or after this date (YYYY-MM-DD). A date window reaches filings older than the recent submissions window by paging into the archive, and with a canvas every Form 4 filed inside it is parsed, up to 100. Structured Form 4 XML begins in mid-2003, so an earlier window finds nothing."
},
"filed_before": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "YYYY-MM-DD"
}
],
"description": "Only read Form 4 filings filed on or before this date (YYYY-MM-DD). Use alone or with filed_after. Without either bound the tool reads the newest Form 4 filings."
},
"transaction_type": {
"enum": [
"purchase",
"sale",
"all"
],
"type": "string",
"default": "all",
"description": "Filter by direction. \"purchase\" = open-market buys (code P). \"sale\" = open-market sells (code S). \"all\" includes grants, awards, exercises, gifts, and other coded transaction types as well."
}
},
"additionalProperties": false
}secedgar_get_insider_transactions output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"issuer_name",
"issuer_cik",
"transactions",
"filings_scanned",
"filings_other_issuer"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"company_not_found",
"ambiguous_company",
"no_filings_found",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a known company. `ambiguous_company`: The company input resolves to multiple entities and the target is ambiguous. `no_filings_found`: A call without a date window finds no Form 4 filings in the recent submissions window. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of transactions shown inline."
},
"notice": {
"type": "string",
"description": "Why the result is empty (the filter, or every scanned filing naming another issuer), and the dataframe pointer when staged."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"truncated": {
"type": "boolean",
"description": "True when Form 4 filings exist past those parsed (the newest-filings sample, or a window's 100-filing or 10-page cap); narrow the window to reach them."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of every parsed transaction, issuer keys on each row, for net buy/sell by insider and cross-issuer joins. Absent when canvas is unavailable or nothing parsed.",
"additionalProperties": false
},
"truncated": {
"type": "boolean",
"description": "True when the inline transactions[] was capped by limit."
},
"issuer_cik": {
"type": "string",
"description": "Issuer CIK, zero-padded to 10 digits."
},
"issuer_name": {
"type": "string",
"description": "Issuer entity name (SEC-conformed)."
},
"transactions": {
"type": "array",
"items": {
"type": "object",
"required": [
"filing_date",
"accession_number",
"reporting_person",
"relationship",
"security_title",
"transaction_code",
"transaction_type",
"is_derivative"
],
"properties": {
"direction": {
"enum": [
"acquire",
"dispose"
],
"type": "string",
"description": "\"acquire\" (buy, award, exercise) or \"dispose\" (sale, gift, return). Absent when shares_traded is."
},
"filing_date": {
"type": "string",
"description": "Date the Form 4 was filed (YYYY-MM-DD)."
},
"relationship": {
"type": "string",
"description": "Relationship to issuer (e.g., \"Director\", \"Officer (CEO)\", \"10% Owner\")."
},
"is_derivative": {
"type": "boolean",
"description": "True for derivative securities (options, RSUs, convertible notes); false for direct equity."
},
"shares_traded": {
"type": "number",
"description": "Shares involved, always positive; direction gives the sign. Absent when the filing omits it."
},
"ownership_type": {
"enum": [
"direct",
"indirect"
],
"type": "string",
"description": "Direct, or indirect (through a trust, family member, etc.). Absent when not reported."
},
"security_title": {
"type": "string",
"description": "Security type (e.g., \"Common Stock\")."
},
"price_per_share": {
"type": "number",
"description": "Price per share in USD; 0 for gifts and RSU awards. Absent when not reported."
},
"accession_number": {
"type": "string",
"description": "Form 4 accession number — pass to secedgar_get_filing for the raw XML."
},
"ownership_nature": {
"type": "string",
"description": "Nature of indirect ownership (e.g., \"By Trust\"). Present only when ownership_type is indirect."
},
"period_of_report": {
"type": "string",
"description": "Transaction date per the filing period (YYYY-MM-DD)."
},
"reporting_person": {
"type": "string",
"description": "Name of the insider who filed the Form 4."
},
"transaction_code": {
"type": "string",
"description": "SEC transaction code: P purchase, S sale, M exercise, A award, G gift, F tax withholding, C conversion, among others."
},
"transaction_date": {
"type": "string",
"description": "Date the transaction occurred (YYYY-MM-DD). Absent on some filings."
},
"transaction_type": {
"type": "string",
"description": "Plain-language name of the code (e.g., \"purchase\", \"conversion_of_derivative\")."
},
"shares_owned_after": {
"type": "number",
"description": "Shares owned after this transaction, as reported. Absent when omitted."
}
},
"description": "One insider transaction parsed from a Form 4 filing.",
"additionalProperties": false
},
"description": "Insider transactions, newest filing first, capped at limit; the dataframe holds the full parsed set."
},
"issuer_ticker": {
"type": "string",
"description": "Issuer ticker symbol when available."
},
"filings_scanned": {
"type": "number",
"description": "Form 4 filings scanned, including those in filings_other_issuer."
},
"filings_other_issuer": {
"type": "number",
"description": "Scanned Form 4 filings naming a different issuer, filed by this company as a reporting owner of another (e.g., a 10% holder of a fund). They are that issuer's activity, so they add no transactions here or in the dataframe."
},
"history_scanned_through": {
"type": "string",
"description": "Filing date of the oldest Form 4 parsed (YYYY-MM-DD). Present only with a date window that held a Form 4."
}
},
"additionalProperties": false
}secedgar_get_insider_transactions annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_institutional_holdings — Get Institutional Holdings
Advertised read-onlyOpen-world
Read an institutional manager's 13F-HR information table for a quarter. company is the filer: a 10-digit CIK, ticker, or name; names outside the ticker file use EDGAR entity search, and ambiguous names return candidates. For managers holding an issuer, use secedgar_find_holders and pass its filer_cik here. Positions carry issuer, CUSIP, shares, whole-USD market value, option designation, and the accessions they came from. Same-period 13F-HR/A amendments are composed in acceptance order: a RESTATEMENT replaces the rows, a NEW HOLDINGS amendment adds its rows, and each amendment reports how it was applied. By default, sub-lines consolidate into positions sorted by value; consolidate=false preserves raw filing order, each filing's rows after the last. Page with limit, offset and returned next_offset. When canvas is available, the full composed positions are staged as df_<id>: inspect with secedgar_dataframe_describe, then aggregate or join on cusip + reporting_period with secedgar_dataframe_query. Managers below $100M in 13(f) securities may not file. Use secedgar_search_filings with forms=["13F-HR"] for broader search.
secedgar_get_institutional_holdings input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"company"
],
"properties": {
"limit": {
"type": "integer",
"default": 20,
"maximum": 1000,
"minimum": 1,
"description": "Maximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20. Capped at 500: a larger value, up to 1000, returns what 500 returns."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Row to start the page at, 0-based, over the ordered position list. Pass the next_offset from the previous response to read the next page — the filing is parsed whole and sliced, so paging is stable and gap-free. An offset at or past the position count returns an empty page."
},
"company": {
"type": "string",
"minLength": 1,
"description": "The institutional filer whose 13F to fetch — a 10-digit CIK (e.g. \"0000102909\" for VANGUARD GROUP INC, the most reliable form), a ticker, or an entity name. A name is matched against the registrants in EDGAR's ticker file first (current and former names) and, when none match, resolved through EDGAR entity search, which covers institutional managers absent from that file; a name matching several filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK. This is NOT the portfolio company — passing an issuer ticker like \"AAPL\" finds that operating company's own filings (it files no 13F), not who holds it; use secedgar_find_holders for that direction."
},
"quarter": {
"type": "string",
"description": "Reporting quarter to target, in \"YYYY-QN\" format (e.g., \"2025-Q4\"), matched exactly against each 13F-HR's period of report. When omitted, returns the most recent 13F-HR in the submissions feed's recent window (the last year or 1,000 filings, whichever holds more). Quarters map to the filing window: Q4 2025 = filings submitted roughly Jan–Mar 2026. A quarter older than the recent window is looked up in the archive, reading forward from the quarter end up to 10 archive pages. A quarter the manager covered with a 13F-NT notice (holdings reported by other managers) fails naming that notice."
},
"consolidate": {
"type": "boolean",
"default": true,
"description": "When true (default), info-table sub-lines for the same security (CUSIP + class + put/call) are summed into one position and results are sorted by market value descending, so `limit` returns the largest distinct holdings. Set false to return raw information-table rows in filing order (one per investment-discretion/manager sub-line), preserving investment_discretion."
}
},
"additionalProperties": false
}secedgar_get_institutional_holdings output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"filer_name",
"filer_cik",
"filing_date",
"accession_number",
"composed_accessions",
"total_holdings_in_filing",
"total_holdings_composed",
"offset",
"holdings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"company_not_found",
"ambiguous_entity",
"no_filings_found",
"no_info_table",
"rate_limited",
"sec_unreachable",
"efts_degraded_response"
],
"description": "Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a known company or institution. `ambiguous_entity`: The name resolves to multiple EDGAR entities (e.g. several filers sharing a legal name). `no_filings_found`: No 13F-HR matches — the entity files none, none exists for the requested quarter in the recent submissions window or the archive pages searched, or the manager filed a 13F-NT notice instead (for the requested quarter, or as its only recent 13F filing when no quarter is given). `no_info_table`: The 13F-HR filing was found but the information table XML document could not be located. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. `efts_degraded_response`: EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of holdings shown inline."
},
"notice": {
"type": "string",
"description": "Amendment composition, discovery, paging, and dataframe guidance."
},
"offset": {
"type": "number",
"description": "Row the returned page starts at, 0-based."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Composed positions, shaped by consolidate; join on cusip + reporting_period. Absent without canvas or holdings.",
"additionalProperties": false
},
"holdings": {
"type": "array",
"items": {
"type": "object",
"required": [
"issuer_name",
"source_accession_numbers"
],
"properties": {
"cusip": {
"type": "string",
"description": "CUSIP. Absent if unreported."
},
"put_call": {
"enum": [
"Put",
"Call"
],
"type": "string",
"description": "Present only on a put or call option position."
},
"issuer_name": {
"type": "string",
"description": "Name of the issuer whose securities are held."
},
"title_of_class": {
"type": "string",
"description": "Security class (COM, CL A, ETF). Absent if unreported."
},
"market_value_usd": {
"type": "number",
"description": "Whole USD at report date; values filed before 2023-01-03 scaled from thousands. Absent if unreported."
},
"investment_discretion": {
"enum": [
"SOLE",
"DFND",
"OTR"
],
"type": "string",
"description": "SOLE sole, DFND shared/advised, OTR other. Absent if unreported or consolidated."
},
"shares_or_principal_type": {
"enum": [
"SH",
"PRN"
],
"type": "string",
"description": "SH shares; PRN debt principal. Absent if unreported."
},
"source_accession_numbers": {
"type": "array",
"items": {
"type": "string"
},
"description": "Accessions the row came from, in application order."
},
"shares_or_principal_amount": {
"type": "number",
"description": "Shares or debt principal. Absent if unreported."
}
},
"description": "One row from the 13F information table.",
"additionalProperties": false
},
"description": "`limit` rows from `offset`: positions by value when consolidate=true, else raw rows in application order."
},
"filer_cik": {
"type": "string",
"description": "CIK of the 13F filer, zero-padded to 10 digits."
},
"truncated": {
"type": "boolean",
"description": "True when the inline holdings[] was capped by limit."
},
"amendments": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"required": [
"accession_number",
"filing_date",
"applied_as",
"amendment_type"
],
"properties": {
"applied_as": {
"enum": [
"restatement",
"new_holdings",
"superseded",
"not_applied"
],
"type": "string",
"description": "Composition role."
},
"filing_date": {
"type": "string",
"description": "Filing date (YYYY-MM-DD)."
},
"amendment_type": {
"enum": [
"RESTATEMENT",
"NEW HOLDINGS"
],
"type": "string",
"description": "Cover-page type."
},
"accession_number": {
"type": "string",
"description": "Accession for secedgar_get_filing."
}
},
"description": "Typed amendment.",
"additionalProperties": false
},
{
"type": "object",
"required": [
"accession_number",
"filing_date",
"applied_as",
"amendment_type",
"unavailable_reason"
],
"properties": {
"applied_as": {
"enum": [
"restatement",
"new_holdings",
"superseded",
"not_applied"
],
"type": "string",
"description": "Composition role."
},
"filing_date": {
"type": "string",
"description": "Filing date (YYYY-MM-DD)."
},
"amendment_type": {
"type": "string",
"const": "UNAVAILABLE",
"description": "Type could not be read."
},
"accession_number": {
"type": "string",
"description": "Accession for secedgar_get_filing."
},
"unavailable_reason": {
"enum": [
"missing_header",
"unreadable_header",
"lookup_failed",
"lookup_stopped"
],
"type": "string",
"description": "Why the type is unavailable; inspect with secedgar_get_filing."
}
},
"description": "Untyped amendment.",
"additionalProperties": false
}
],
"description": "Same-period 13F-HR/A."
},
"description": "Known amendments, newest filed first. Absent if none."
},
"filer_name": {
"type": "string",
"description": "Institutional filer name (the 13F submitter)."
},
"filing_date": {
"type": "string",
"description": "Original 13F-HR filing date (YYYY-MM-DD)."
},
"next_offset": {
"type": "number",
"description": "Offset for the next page. Absent on the last page."
},
"total_positions": {
"type": "number",
"description": "Distinct positions before paging. Only with consolidate=true."
},
"accession_number": {
"type": "string",
"description": "Original 13F-HR accession for secedgar_get_filing."
},
"reporting_period": {
"type": "string",
"description": "Cover-page quarter end (YYYY-MM-DD). Absent if omitted."
},
"composed_accessions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Accessions whose rows form holdings, in application order."
},
"total_holdings_composed": {
"type": "number",
"description": "Composed raw row count before consolidation or paging."
},
"total_holdings_in_filing": {
"type": "number",
"description": "Original 13F-HR raw row count."
},
"amendment_search_complete": {
"type": "boolean",
"description": "False if archive discovery was bounded or unavailable."
}
},
"additionalProperties": false
}secedgar_get_institutional_holdings annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_find_holders — Find Holders
Advertised read-onlyOpen-world
Find which institutional managers reported holding an issuer, by searching 13F-HR information tables for one reporting quarter. This is the reverse direction of secedgar_get_institutional_holdings: that tool takes a manager and returns its portfolio, this one takes an issuer and returns its managers — pass a returned filer_cik plus the same quarter to read the actual position. Searching by cusip is the precise path, matching the identifier the information table itself carries; without it the issuer name is matched as a phrase against the filing text, which both over-matches (unrelated issuers sharing a word) and under-matches (managers writing the name differently), so prefer cusip whenever one is known. A CUSIP cannot be derived from a ticker here — read one off any 13F information table returned by secedgar_get_institutional_holdings. The returned list is unranked: the search index scores by text relevance, which carries no signal about position size, and no ordering by shares or market value is available without opening each filing. Managers holding under $100M in 13(f) securities are exempt from filing at all. When more managers match than fit inline, the full fetched set is staged as df_<id> — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.
secedgar_find_holders input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"issuer"
],
"properties": {
"cusip": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^[0-9A-Za-z]{9}$",
"description": "9-character CUSIP/CINS"
}
],
"description": "The issuer's 9-character CUSIP (e.g. \"037833100\" for Apple common stock; foreign issuers use a CINS starting with a letter, e.g. \"H1467J104\"). The precise match key — information tables identify every position by CUSIP, so this avoids the name-phrase misses. Each share class has its own CUSIP, so a multi-class issuer needs one call per class. Read a CUSIP off the holdings returned by secedgar_get_institutional_holdings."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 1000,
"minimum": 1,
"description": "Filer rows returned inline. The full fetched set (up to 500 rows) is materialized as a dataframe when a canvas is available. Default 20. Capped at 100: a larger value, up to 1000, returns what 100 returns."
},
"issuer": {
"type": "string",
"minLength": 1,
"description": "The portfolio company whose holders you want — a ticker (\"AAPL\"), a 10-digit CIK (\"0000320193\"), or a company name. Without cusip, this resolves to the company's EDGAR-conformed name, and that name, minus a trailing qualifier such as \\DE\\ or /OH/, is phrase-matched against 13F information tables, so it must identify one company. With cusip supplied, it is used only to label the result."
},
"quarter": {
"anyOf": [
{
"type": "string",
"const": ""
},
{
"type": "string",
"pattern": "^\\d{4}-Q[1-4]$",
"description": "YYYY-QN"
}
],
"description": "Reporting quarter to search, \"YYYY-QN\" (e.g. \"2026-Q1\"). Omit for the newest quarter whose 45-day filing deadline has passed — the applied quarter and its filing window are echoed in the response. A quarter still inside its deadline returns only the managers that filed early, so its set is incomplete until the deadline passes."
}
},
"additionalProperties": false
}secedgar_find_holders output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"issuer",
"search_mode",
"search_key",
"quarter",
"filed_from",
"filed_to",
"total_filings",
"total_is_exact",
"fetched",
"holders_in_quarter",
"holders",
"ordering"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"issuer_not_found",
"ambiguous_issuer",
"rate_limited",
"sec_unreachable",
"efts_degraded_response"
],
"description": "Machine-readable failure mode. Declared by this tool: `issuer_not_found`: No cusip was given and the issuer does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies and no cusip was given. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. `efts_degraded_response`: EDGAR full-text search answered without results — its search backend failed to run the search on every attempt made (a connection or timeout failure, retried like a request SEC never answered), refused the request (upstreamErrorType and upstreamErrorMessage carry its error, and the request is not retried), or sent a payload with no hit list. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of filers shown inline."
},
"issuer": {
"type": "string",
"description": "The issuer input, echoed."
},
"notice": {
"type": "string",
"description": "Continuation, search coverage, shared names, empty results, and dataframe guidance."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"truncated": {
"type": "boolean",
"description": "True when the fetched sample may omit matching documents."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Fetched managers keyed by issuer and quarter for joins. Absent if inline fits, canvas is unavailable or staging fails.",
"additionalProperties": false
},
"fetched": {
"type": "number",
"description": "Filings retrieved, at most 500; equals total_filings when the window fit."
},
"holders": {
"type": "array",
"items": {
"type": "object",
"required": [
"filer_name",
"filer_cik",
"accession_number",
"filing_date"
],
"properties": {
"form": {
"type": "string",
"description": "\"13F-HR\", or \"13F-HR/A\" for an amendment. Absent when the index carries no form tag."
},
"filer_cik": {
"type": "string",
"description": "Filer CIK, zero-padded to 10 digits; pass as company to secedgar_get_institutional_holdings."
},
"filer_name": {
"type": "string",
"description": "Institutional manager that filed, ticker/CIK parentheticals stripped."
},
"filing_date": {
"type": "string",
"description": "Date the 13F-HR was submitted (YYYY-MM-DD)."
},
"accession_number": {
"type": "string",
"description": "Accession number of the 13F-HR — pass to secedgar_get_filing."
}
},
"description": "One institutional manager reporting a position in this issuer.",
"additionalProperties": false
},
"description": "One page of filers, capped at limit; order says nothing about position size."
},
"quarter": {
"type": "string",
"description": "Reporting quarter searched, \"YYYY-QN\": the requested one or the default."
},
"filed_to": {
"type": "string",
"description": "End of the filing window searched (YYYY-MM-DD)."
},
"ordering": {
"type": "string",
"description": "How the holder list is ordered, and what that ordering does not mean."
},
"truncated": {
"type": "boolean",
"description": "True when the inline holders list was capped."
},
"filed_from": {
"type": "string",
"description": "Start of the filing window searched (YYYY-MM-DD)."
},
"search_key": {
"type": "string",
"description": "The exact term searched — the CUSIP, or the quoted name minus any trailing qualifier."
},
"search_mode": {
"enum": [
"cusip",
"name"
],
"type": "string",
"description": "\"cusip\" matches the information table's identifier; \"name\" phrase-matches filing text, looser both ways."
},
"total_filings": {
"type": "number",
"description": "Matching documents in the filing window, including amendments; holders_in_quarter deduplicates managers and filters period."
},
"total_is_exact": {
"type": "boolean",
"description": "False when total_filings is a lower bound (the index capped the count)."
},
"holders_in_quarter": {
"type": "number",
"description": "Distinct in-quarter managers in the fetched sample and dataframe; latest filing per CIK wins, other periods excluded."
},
"resolved_issuer_cik": {
"type": "string",
"description": "CIK of the resolved issuer, zero-padded to 10 digits. Absent when cusip was supplied."
},
"resolved_issuer_name": {
"type": "string",
"description": "EDGAR-conformed name the issuer resolved to. Absent when cusip was supplied."
}
},
"additionalProperties": false
}secedgar_find_holders annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_beneficial_owners — Get Beneficial Owners
Advertised read-onlyOpen-world
List the 5%-and-over beneficial owners of a public company, parsed from the structured SCHEDULE 13D and SCHEDULE 13G filings made about it. The input is the ISSUER — the company being held — which is the opposite direction from secedgar_get_institutional_holdings, where the input is the manager. 13D is the activist form and carries the filer's stated purpose of the transaction; 13G is the passive form and has no purpose field at all, which is the substantive difference between a stake that intends to influence control and one that does not. Every filing is returned with each reporting person listed separately, because voting power, dispositive power, and percent of class are reported per person even on a joint filing where several funds and their controlling principal report overlapping shares — summing those percentages double-counts the same position. Coverage starts at 2024-12-18, when SEC replaced the legacy SC 13D / SC 13G text filings with this XML format; earlier stakes are readable but not parseable, and the response reports how many of them the issuer has. The full parsed set is materialized as df_<id> when a canvas is available, one row per reporting person, so it joins against the insider dataframes on issuer CIK and the 13F and NPORT-P dataframes on CUSIP — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.
secedgar_get_beneficial_owners input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"issuer"
],
"properties": {
"limit": {
"type": "integer",
"default": 10,
"maximum": 1000,
"minimum": 1,
"description": "Number of successfully parsed filings naming the requested issuer to return, newest first. Other-issuer schedules and failed documents do not consume this limit; at most 50 documents are examined. Default 10. Capped at 20: a larger value, up to 1000, returns what 20 returns."
},
"issuer": {
"type": "string",
"minLength": 1,
"description": "The company whose blockholders you want — a ticker (\"AAPL\"), a 10-digit CIK (\"0000320193\"), or a company name. This is the subject company of the schedule, not the investor filing it; passing an investment manager here returns the schedules filed about that manager, which is almost always empty."
},
"form_kind": {
"enum": [
"all",
"13D",
"13G"
],
"type": "string",
"default": "all",
"description": "Which schedule to return. \"13D\" is the activist form, filed by a holder that may seek to influence control and carrying a stated purpose of transaction. \"13G\" is the passive form, available to institutions and holders under 20% that certify no control intent. \"all\" (default) returns both, newest first."
},
"include_amendments": {
"type": "boolean",
"default": true,
"description": "Whether to include amendments (SCHEDULE 13D/A, SCHEDULE 13G/A). Amendments carry the current position and are how an ongoing stake is tracked, so they are included by default. Set false to see only filings that opened a new position."
}
},
"additionalProperties": false
}secedgar_get_beneficial_owners output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"issuer",
"issuer_cik",
"issuer_name",
"form_kind",
"total_structured_filings",
"filings_parsed",
"filings_examined",
"filings_excluded_other_issuer",
"filings_not_examined",
"filings_failed",
"partial",
"structured_coverage_from",
"legacy_filings_before_coverage",
"filings"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "Result limit or document ceiling that stopped scanning."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"issuer_not_found",
"ambiguous_issuer",
"no_filings_found",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `issuer_not_found`: The issuer input does not resolve to a known EDGAR company. `ambiguous_issuer`: The issuer name matches several EDGAR companies. `no_filings_found`: The issuer has no structured SCHEDULE 13D/13G filings matching the requested form kind. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of filings returned."
},
"issuer": {
"type": "string",
"description": "The issuer input, echoed."
},
"notice": {
"type": "string",
"description": "Exclusions, document recovery, scan bounds, cut text, and dataframe guidance."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"truncated": {
"type": "boolean",
"description": "True when indexed schedules remain unexamined."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe with one row per reporting person across parsed filings; joins insider dataframes on issuer_cik, and 13F and NPORT-P dataframes on cusip. Absent when canvas is unavailable or nothing parsed.",
"additionalProperties": false
},
"filings": {
"type": "array",
"items": {
"type": "object",
"required": [
"form",
"schedule",
"is_amendment",
"accession_number",
"filing_date",
"cusips",
"purpose_truncated",
"reporting_persons"
],
"properties": {
"form": {
"type": "string",
"description": "EDGAR form name, e.g. \"SCHEDULE 13D\" or \"SCHEDULE 13G/A\"."
},
"cusips": {
"type": "array",
"items": {
"type": "string"
},
"description": "CUSIPs of the subject class from the cover page. Empty when none listed."
},
"schedule": {
"enum": [
"13D",
"13G"
],
"type": "string",
"description": "Which schedule this is — 13D activist, 13G passive."
},
"event_date": {
"type": "string",
"description": "Date of the event that required the filing (YYYY-MM-DD). Absent when the cover page omits it."
},
"filing_date": {
"type": "string",
"description": "Date the schedule was submitted (YYYY-MM-DD)."
},
"is_amendment": {
"type": "boolean",
"description": "True when the form name carries the /A suffix."
},
"security_class": {
"type": "string",
"description": "Class of securities the schedule covers; percentages are of this class only."
},
"accession_number": {
"type": "string",
"description": "Accession number — pass to secedgar_get_filing for the full document."
},
"amendment_number": {
"type": "string",
"description": "Amendment sequence from the cover page. Absent on an original filing."
},
"purpose_truncated": {
"type": "boolean",
"description": "True when purpose_of_transaction holds only its first 5,000 characters; secedgar_get_filing has it whole."
},
"reporting_persons": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"person_types",
"notes_truncated"
],
"properties": {
"cik": {
"type": "string",
"description": "Reporting person CIK. 13D only; the 13G cover page has no CIK field."
},
"name": {
"type": "string",
"description": "Reporting person as named on the cover page."
},
"notes": {
"type": "string",
"description": "The filer's cover-page footnote as filed, often the share count behind the percentage."
},
"citizenship": {
"type": "string",
"description": "SEC citizenship or place-of-organization code: a US state (\"DE\") or SEC country code (\"E9\" Cayman Islands)."
},
"person_types": {
"type": "array",
"items": {
"type": "string"
},
"description": "SEC reporting-person codes: IN individual, CO corporation, PN partnership, IA investment adviser, HC holding company, OO other."
},
"notes_truncated": {
"type": "boolean",
"description": "True when notes holds only its first 2,000 characters; secedgar_get_filing has it whole."
},
"percent_of_class": {
"type": "number",
"description": "Percent of the class this person beneficially owns (0-100). Joint filers report overlapping shares, so these do not sum."
},
"sole_voting_power": {
"type": "number",
"description": "Shares this person alone may vote."
},
"shared_voting_power": {
"type": "number",
"description": "Shares this person votes jointly with another party."
},
"aggregate_amount_owned": {
"type": "number",
"description": "Shares beneficially owned by this person. Absent when none is reported, as on an exit amendment."
},
"sole_dispositive_power": {
"type": "number",
"description": "Shares this person alone may sell or transfer."
},
"excludes_certain_shares": {
"type": "boolean",
"description": "True when the aggregate excludes shares this person disclaims. Absent when the filing does not say."
},
"shared_dispositive_power": {
"type": "number",
"description": "Shares this person may sell or transfer jointly with another party."
}
},
"description": "One reporting person from the schedule cover page.",
"additionalProperties": false
},
"description": "Every reporting person; a joint filing lists each fund, adviser, and principal separately."
},
"purpose_of_transaction": {
"type": "string",
"description": "Item 4 purpose of transaction as filed; 13D only. Absent on 13G and on an amendment that restates none."
}
},
"description": "One SCHEDULE 13D or 13G filing made about this issuer.",
"additionalProperties": false
},
"description": "Blockholder filings, newest first, capped at limit."
},
"partial": {
"type": "boolean",
"description": "True when filings_failed is nonempty, independently of truncation."
},
"form_kind": {
"enum": [
"all",
"13D",
"13G"
],
"type": "string",
"description": "The schedule filter applied — the requested value, or the default \"all\"."
},
"truncated": {
"type": "boolean",
"description": "True when schedules remain unexamined after the result limit or 50-document ceiling."
},
"issuer_cik": {
"type": "string",
"description": "CIK of the resolved issuer, zero-padded to 10 digits."
},
"issuer_name": {
"type": "string",
"description": "EDGAR-conformed name of the resolved issuer."
},
"filings_failed": {
"type": "array",
"items": {
"type": "object",
"required": [
"accession_number",
"reason"
],
"properties": {
"reason": {
"enum": [
"document_not_found",
"unparseable"
],
"type": "string",
"description": "Document returned 404, or could not be parsed with a usable issuer CIK."
},
"accession_number": {
"type": "string",
"description": "Accession to inspect with secedgar_get_filing."
}
},
"description": "One failed document.",
"additionalProperties": false
},
"description": "Failures in scan order; successes retained."
},
"filings_parsed": {
"type": "number",
"description": "Matching parsed filings, capped by limit."
},
"filings_examined": {
"type": "number",
"description": "Matches + exclusions + failures; at most 50 documents."
},
"filings_not_examined": {
"type": "number",
"description": "Indexed schedules beyond the result limit or 50-document ceiling."
},
"structured_coverage_from": {
"type": "string",
"description": "First date SEC required this XML format (YYYY-MM-DD); earlier filings cannot be parsed here."
},
"total_structured_filings": {
"type": "number",
"description": "Indexed 13D/13G schedules matching form/amendment filters in the recent submissions window."
},
"filings_excluded_other_issuer": {
"type": "number",
"description": "Schedules naming another issuer; no rows returned."
},
"legacy_filings_before_coverage": {
"type": "number",
"description": "Legacy SC 13D / SC 13G filings (pre-2024-12-18) in the recent submissions window; find them with secedgar_search_filings. A floor: the window holds the last year or 1,000 filings."
}
},
"additionalProperties": false
}secedgar_get_beneficial_owners annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_get_fund_holdings — Get Fund Holdings
Advertised read-onlyOpen-world
List what an ETF or mutual fund holds, parsed from the NPORT-P portfolio report it files with the SEC every quarter. The input is the fund — a ticker like VOO, a fund series ID, or the registrant trust — which is the opposite direction from the ownership tools: secedgar_get_institutional_holdings and secedgar_find_holders answer who owns a company, this answers what a fund owns. Each position carries the security name, CUSIP/ISIN/LEI where the filer reports them, share balance, market value in USD, and percent of the fund's net assets, alongside fund-level net assets and total assets. Positions are returned largest-first by percent of net assets, one page of limit rows starting at offset; the full report registers as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query, which is how a fund running to thousands of positions is aggregated or joined against the 13F and insider dataframes. An NPORT-P covers exactly one fund series and a registrant trust files one report per series, so a trust with several funds needs the specific fund named — pass its ticker or series_id. Reports publish roughly two months after the period they cover, so every result is dated: the holdings are the portfolio as of report_period_date, not as of today.
secedgar_get_fund_holdings input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"fund"
],
"properties": {
"fund": {
"type": "string",
"minLength": 1,
"description": "The fund whose portfolio you want — a fund ticker (\"VOO\", \"SCHD\"), an SEC fund series ID (\"S000002839\"), or a 10-digit CIK. A ticker names one share class of one series and routes directly; a CIK names the registrant, which files a separate report per series and needs series_id when it runs more than one fund. Fund trusts are indexed by ticker and series, not by name, so a trust name only resolves for a fund that trades under its own name (\"SPDR S&P 500 ETF Trust\") — pass the CIK otherwise."
},
"limit": {
"type": "integer",
"default": 20,
"maximum": 1000,
"minimum": 1,
"description": "Number of positions to return inline, largest first by percent of net assets. Default 20. A broad index fund reports thousands of positions, so the inline list is a preview — read the whole portfolio from the dataframe, or page it with offset. Capped at 100: a larger value, up to 1000, returns what 100 returns."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Position to start the page at, 0-based, over the full ordered holdings list. Pass the returned next_offset to read the next page — the report is parsed whole and sliced, so paging is stable and gap-free."
},
"series_id": {
"type": "string",
"pattern": "^S\\d{9}$",
"description": "SEC fund series identifier (\"S000002839\"), naming which fund of the registrant to report. Takes precedence over any series the fund input implies. Series IDs come back on fund results from secedgar_company_search and in the series list of a series_required error."
},
"report_date": {
"type": "string",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"description": "Target a specific reporting period by its last day (YYYY-MM-DD), e.g. \"2025-12-31\". Omit for the most recent report. Period ends follow the fund's own fiscal quarters, which are not always calendar quarters — Direxion funds report to February, May, August, and November. available_report_periods in the response lists the ones this call identified; a period missing from that list is still worth requesting directly, since a report the submissions window no longer dates is dated by reading it."
}
},
"additionalProperties": false
}secedgar_get_fund_holdings output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"fund",
"class_ids",
"registrant_cik",
"registrant_name",
"filing_date",
"form",
"accession_number",
"total_holdings",
"offset",
"available_report_periods",
"holdings",
"as_of"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"form": {
"type": "string",
"description": "EDGAR form name — \"NPORT-P\", or \"NPORT-P/A\" for an amended report."
},
"fund": {
"type": "string",
"description": "The fund input, echoed."
},
"as_of": {
"type": "string",
"description": "The portfolio date these holdings are reported as of, and the publication lag behind it."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"fund_not_found",
"ambiguous_fund",
"series_required",
"no_filings_found",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `fund_not_found`: The fund input resolves to neither an EDGAR company nor a known fund series. `ambiguous_fund`: The fund name matches several EDGAR companies. `series_required`: The input resolves to a registrant trust that files reports for more than one fund series. `no_filings_found`: No NPORT-P report exists for this fund, or none covers the report_date requested. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of positions shown inline."
},
"notice": {
"type": "string",
"description": "Guidance when the report carried no positions or the page fell past the end."
},
"offset": {
"type": "number",
"description": "Position the returned page starts at, 0-based."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of every position, each row carrying the fund keys; joins 13F and 13D/G dataframes on cusip. Absent when canvas is unavailable or the report had no positions.",
"additionalProperties": false
},
"holdings": {
"type": "array",
"items": {
"type": "object",
"required": [
"name"
],
"properties": {
"lei": {
"type": "string",
"description": "Legal Entity Identifier of the issuer, when reported."
},
"isin": {
"type": "string",
"description": "ISIN. Absent when the filer reports another identifier."
},
"name": {
"type": "string",
"description": "Issuer name as reported. Derivatives often report \"N/A\" and name the instrument in title."
},
"cusip": {
"type": "string",
"description": "9-character CUSIP. Absent when the filer omits it."
},
"title": {
"type": "string",
"description": "The filer's own title for the security, often an abbreviated trading name."
},
"units": {
"type": "string",
"description": "What balance counts — NS number of shares, PA principal amount, NC number of contracts, OU other."
},
"balance": {
"type": "number",
"description": "Units held, in whatever `units` names (shares, principal, or contracts)."
},
"country": {
"type": "string",
"description": "ISO 3166 country of investment."
},
"currency": {
"type": "string",
"description": "ISO 4217 denomination; value_usd stays USD."
},
"value_usd": {
"type": "number",
"description": "Market value of the position in USD at the report date."
},
"asset_category": {
"type": "string",
"description": "SEC asset-type code (EC equity-common, EP equity-preferred, DBT debt, RA repurchase agreement, STIV short-term investment vehicle, DE derivative), or the filer's own label for Other (\"Right\")."
},
"payoff_profile": {
"type": "string",
"description": "\"Long\", \"Short\", or \"N/A\" for instruments with no direction."
},
"issuer_category": {
"type": "string",
"description": "SEC issuer-type code (CORP corporate, MUN municipal, USGSE US government-sponsored, RF registered fund), or the filer's own label for Other (\"Future\")."
},
"percent_of_net_assets": {
"type": "number",
"description": "Percent of the fund's net assets as the filer computes it; negative on short positions, so not bounded at 0."
}
},
"description": "One position from the fund portfolio.",
"additionalProperties": false
},
"description": "One page of positions, `limit` rows starting at `offset`, largest first by percent of net assets."
},
"class_ids": {
"type": "array",
"items": {
"type": "string"
},
"description": "SEC class IDs covered; one report covers every class of the series."
},
"series_id": {
"type": "string",
"description": "SEC series ID of the fund. Absent when the registrant files as a single fund with no series."
},
"truncated": {
"type": "boolean",
"description": "True when the inline holdings list was capped by limit."
},
"filing_date": {
"type": "string",
"description": "Date the report was submitted to EDGAR (YYYY-MM-DD)."
},
"next_offset": {
"type": "number",
"description": "Offset for the next page. Absent on the last page."
},
"series_name": {
"type": "string",
"description": "Fund name on the report; a single-registrant closed-end fund names itself here, with no series_id. Absent when blank or \"N/A\"."
},
"net_assets_usd": {
"type": "number",
"description": "Fund net assets in USD at the report date — the denominator of percent_of_net_assets."
},
"registrant_cik": {
"type": "string",
"description": "CIK of the registrant trust, zero-padded to 10 digits."
},
"total_holdings": {
"type": "number",
"description": "Positions in the full report, before offset and limit."
},
"is_final_filing": {
"type": "boolean",
"description": "True when the fund marks this its last filing for the series (liquidation or merger). Absent when unstated."
},
"registrant_name": {
"type": "string",
"description": "EDGAR-conformed name of the registrant trust."
},
"accession_number": {
"type": "string",
"description": "Accession number — pass to secedgar_get_filing for the full document."
},
"total_assets_usd": {
"type": "number",
"description": "Fund total assets in USD at the report date."
},
"report_period_end": {
"type": "string",
"description": "Fiscal year end the reporting period falls in (YYYY-MM-DD), not the portfolio date."
},
"report_period_date": {
"type": "string",
"description": "Portfolio date (YYYY-MM-DD): positions as of this date, not today. Absent only when the filer omits it."
},
"publication_lag_days": {
"type": "number",
"description": "Days from the portfolio date to the filing date. Absent when the report omits its period date."
},
"total_liabilities_usd": {
"type": "number",
"description": "Fund total liabilities in USD at the report date."
},
"available_report_periods": {
"type": "array",
"items": {
"type": "string"
},
"description": "Period end dates of this fund's reports, newest first: what report_date can address, about a decade back. A trust filing thousands of reports a year can miss periods here that report_date still reaches."
}
},
"additionalProperties": false
}secedgar_get_fund_holdings annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_fetch_frames — Secedgar Fetch Frames
Advertised read-onlyOpen-world
Fetch SEC XBRL frames for one concept × one period across all reporting companies. Inline response returns a page of the ranked companies — start at the top or pass offset/next_offset to walk further down the ranking; the full frames response (all reporters) is materialized as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query. Accepts friendly names like "revenue" or "assets" (discover via secedgar_search_concepts) or raw XBRL tags. One call hits one XBRL tag — when a friendly name maps to multiple same-meaning tags, the response's `unqueried_tags` lists the others; call again per tag and UNION/COALESCE in SQL with an analysis-specific priority (e.g. SalesRevenueGoodsNet is goods-only). The response's `related_tags` separately flags alternate-DEFINITION tags a meaningful share of filers use as their primary line (e.g. cash incl. restricted cash, equity incl. noncontrolling interest) — a whole-universe screen on the base tag silently omits those filers; query them separately, but do not blindly union (the semantics differ). Response includes `value_distribution` and `period_end_range` to flag XBRL scale-factor anomalies and fiscal-year mixing. SEC publishes frames for us-gaap and dei tags only, and `taxonomy` picks which of the two a raw tag is read from (dei for cover-page tags such as EntityCommonStockSharesOutstanding); a friendly name keeps its own mapped taxonomy. There are no ifrs-full frames, so IFRS (20-F) filers are absent from every frame; read them per company with secedgar_get_financials or secedgar_compare_companies under taxonomy ifrs-full.
secedgar_fetch_frames input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"concept",
"period"
],
"properties": {
"sort": {
"enum": [
"desc",
"asc"
],
"type": "string",
"default": "desc",
"description": "Sort direction. \"desc\" for highest values first (typical for revenue, assets). \"asc\" for lowest values."
},
"unit": {
"enum": [
"USD",
"USD-per-shares",
"USD/shares",
"shares",
"pure"
],
"type": "string",
"default": "USD",
"description": "Unit of measure. Use \"USD-per-shares\" (or equivalently \"USD/shares\") for EPS, \"shares\" for share counts, \"pure\" for ratios. Ignored when concept resolves to a friendly name with a known unit."
},
"limit": {
"type": "integer",
"default": 25,
"maximum": 1000,
"minimum": 1,
"description": "Number of companies to return. Capped at 100: a larger value, up to 1000, returns what 100 returns."
},
"offset": {
"type": "integer",
"default": 0,
"maximum": 9007199254740991,
"minimum": 0,
"description": "Rank to start the page at, 0-based, over the sorted frame. Pass the next_offset from the previous response to read the next page — the ranked list is fetched whole and sliced, so paging is stable and gap-free. An offset at or past total_companies returns an empty page."
},
"period": {
"type": "string",
"pattern": "^CY\\d{4}(Q[1-4]I?)?$",
"minLength": 1,
"description": "Calendar period. Use duration periods (no I suffix) for income/cash-flow items: \"CY2023\" (full year), \"CY2024Q2\" (single quarter). Use instant periods (I suffix) for balance-sheet items: \"CY2023Q4I\" (snapshot at Q4 close)."
},
"concept": {
"type": "string",
"minLength": 1,
"description": "Financial concept — same friendly names as secedgar_get_financials (e.g., \"revenue\", \"assets\", \"eps_basic\") or raw XBRL tag."
},
"taxonomy": {
"enum": [
"us-gaap",
"dei"
],
"type": "string",
"default": "us-gaap",
"description": "Frames namespace a raw XBRL tag is read from: us-gaap for financial-statement tags, dei for cover-page entity tags such as EntityCommonStockSharesOutstanding. SEC publishes frames for no other taxonomy. A friendly name keeps its own mapped taxonomy (shares_outstanding reads dei) unless dei is passed, which reads its tags from dei instead — the same rule as secedgar_get_financials."
}
},
"additionalProperties": false
}secedgar_fetch_frames output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"concept",
"taxonomy",
"period",
"unit",
"label",
"total_companies",
"offset",
"data",
"unqueried_tags",
"related_tags",
"value_distribution",
"period_end_range",
"caveats"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The limit cap applied."
},
"data": {
"type": "array",
"items": {
"type": "object",
"required": [
"rank",
"company_name",
"cik",
"value",
"period_end",
"accession_number"
],
"properties": {
"cik": {
"type": "string",
"description": "Company CIK, zero-padded to 10 digits."
},
"rank": {
"type": "number",
"description": "Rank in sorted order."
},
"value": {
"type": "number",
"description": "Reported value."
},
"ticker": {
"type": "string",
"description": "Ticker symbol (if available)."
},
"location": {
"type": "string",
"description": "Business location (state or country). Absent when SEC has none."
},
"period_end": {
"type": "string",
"description": "Period end date (YYYY-MM-DD)."
},
"company_name": {
"type": "string",
"description": "Entity name."
},
"accession_number": {
"type": "string",
"description": "Source filing for secedgar_get_filing."
}
},
"description": "One company's reported value for this metric and period.",
"additionalProperties": false
},
"description": "Ranked companies for this metric."
},
"unit": {
"type": "string",
"description": "Unit of measure, in dashed form (e.g., \"USD-per-shares\")."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"unknown_concept",
"no_data",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `unknown_concept`: The concept input is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `no_data`: Concept resolves but no companies report the tag this call read for the requested period and unit. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"label": {
"type": "string",
"description": "Human-readable concept label."
},
"shown": {
"type": "number",
"description": "Number of companies shown inline."
},
"notice": {
"type": "string",
"description": "Guidance when the requested offset lands past the end of the ranked list."
},
"offset": {
"type": "number",
"description": "Rank the returned page starts at, 0-based."
},
"period": {
"type": "string",
"description": "Calendar period the data was fetched for, echoed from input."
},
"caveats": {
"type": "array",
"items": {
"type": "string"
},
"description": "Completeness warnings, else empty: quarterly frames (CY####Q#) omit fiscal-Q4 filers; annual NetIncomeLoss rows may be proxy pay-versus-performance figures; an annual frame still open or in its 10-K window may hold 10-Q trailing-twelve-month figures; top rows may be split or scale artifacts."
},
"concept": {
"type": "string",
"description": "XBRL tag the data was actually fetched against (after resolving any friendly name)."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of the full frame, every reporter. Absent when canvas is unavailable or staging failed.",
"additionalProperties": false
},
"taxonomy": {
"type": "string",
"description": "Frames namespace the tag was read from (us-gaap or dei); a friendly name mapped to dei reads dei."
},
"truncated": {
"type": "boolean",
"description": "True when the inline data[] was capped by limit."
},
"next_offset": {
"type": "number",
"description": "Offset for the next page down the ranking. Absent on the last page."
},
"related_tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"tag",
"note"
],
"properties": {
"tag": {
"type": "string",
"description": "Alternate XBRL tag those filers report under."
},
"note": {
"type": "string",
"description": "How this tag differs in definition from the queried tag."
}
},
"description": "One alternate-definition tag and the reason it differs.",
"additionalProperties": false
},
"description": "Alternate-definition tags many filers use as their primary line (e.g., cash including restricted cash); those filers are absent from data. Fetch each separately; never blindly UNION, since definitions differ. Empty when none is known."
},
"unqueried_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Same-meaning mapped tags this call did not query (e.g., SalesRevenueNet for revenue); their filers are absent from data, so fetch each and UNION/COALESCE in SQL. Empty for raw tags and single-tag concepts."
},
"total_companies": {
"type": "number",
"description": "Total companies reporting this metric for this period."
},
"period_end_range": {
"type": "object",
"required": [
"min",
"max"
],
"properties": {
"max": {
"type": "string",
"description": "Latest period_end across all rows (YYYY-MM-DD)."
},
"min": {
"type": "string",
"description": "Earliest period_end across all rows (YYYY-MM-DD)."
}
},
"description": "Range of period_end dates; filers report on their own fiscal years, so \"CY2023\" can span 2023-01-31 to 2024-12-31, mixing fiscal periods.",
"additionalProperties": false
},
"value_distribution": {
"type": "object",
"required": [
"median",
"p95",
"max",
"max_to_p95_ratio"
],
"properties": {
"max": {
"type": "number",
"description": "Maximum reported value."
},
"p95": {
"type": "number",
"description": "95th-percentile reported value."
},
"median": {
"type": "number",
"description": "Median reported value across all reporters in the frame."
},
"max_to_p95_ratio": {
"type": "number",
"description": "Max divided by p95. Heavy-tail frames sit near 10–50×; above ~200× usually means a filer-side scale-factor error, so check the top rows of data before trusting rankings."
}
},
"description": "Distribution across the full frame; max_to_p95_ratio is the outlier signal.",
"additionalProperties": false
}
},
"additionalProperties": false
}secedgar_fetch_frames annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_compare_companies — Secedgar Compare Companies
Advertised read-onlyOpen-world
Compare 2-10 named companies across 1-8 XBRL concepts, aligned on fiscal years (annual) or calendar quarters (quarterly). This is the middle shape between secedgar_get_financials (one company, one concept, full history) and secedgar_fetch_frames (one concept, one period, every reporting company) — reach for it when the question names the companies. One companyfacts read per company, resolved through the same frame dedup and tag priority as secedgar_get_financials so the numbers agree. Balance-sheet and entity-info concepts are filed as point-in-time values: an annual matrix takes each company’s fiscal-year-end snapshot and places it in the period of the fiscal year it closes, beside that year’s income-statement lines (interim and cover-date snapshots stay out), and a quarterly matrix aligns each snapshot on the calendar quarter it falls in. The inline matrix covers the most recent periods up to `periods`, trimmed further when companies x concepts x periods is too large to return in one response; the full aligned series is materialized as df_<id> for growth rates and spreads — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query. A company that fails to resolve is reported in failed_companies and the comparison proceeds with the rest, and a company that does not report a concept is reported in gaps with the tags that were tried — never interpolated or zero-filled. A company named twice (a ticker and its CIK) is read once, under the first input. Where the schema accepts a longer list, companies past the first 10 and concepts past the first 8 distinct are not read; they come back in deferred_companies and deferred_concepts to re-call with. A company that reports a concept only for periods older than the inline window is named in caveats with its newest period. A concept that is neither a friendly name nor an XBRL tag is reported once in unknown_concepts with the closest supported names, and fails the call only when every concept is one. Off-calendar filers and unit mismatches are surfaced in caveats rather than silently mixed.
secedgar_compare_companies input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"companies",
"concepts"
],
"properties": {
"periods": {
"type": "integer",
"default": 4,
"maximum": 1000,
"minimum": 1,
"description": "Upper bound on how many recent periods the inline matrix covers, newest first — not a guarantee. The matrix is companies x concepts x periods cells, and the inline window drops further older periods when that product is too large to return in one response. The full aligned series is always registered to the dataframe, so dropped periods stay queryable via secedgar_dataframe_query. Capped at 12: a larger value, up to 1000, returns what 12 returns."
},
"concepts": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "Friendly concept name or raw XBRL tag."
},
"maxItems": 100,
"minItems": 1,
"description": "Concepts to compare — friendly names like \"revenue\" or \"net_income\" (discover them with secedgar_search_concepts) or raw XBRL tags. The first 8 distinct concepts are compared, spellings of one concept counting once and an unrecognized name not at all; a longer list, up to 100, returns each input naming a further concept unread in deferred_concepts."
},
"taxonomy": {
"enum": [
"us-gaap",
"ifrs-full"
],
"type": "string",
"default": "us-gaap",
"description": "XBRL taxonomy to resolve concepts under. Use ifrs-full only when every company in the list reports under IFRS; mixing IFRS and US GAAP filers in one call resolves them all under the same taxonomy."
},
"companies": {
"type": "array",
"items": {
"type": "string",
"minLength": 1,
"description": "Ticker symbol or CIK number."
},
"maxItems": 100,
"minItems": 2,
"description": "Companies to compare, as ticker symbols (preferred) or CIK numbers. A company that does not resolve is reported in failed_companies and the rest of the comparison still runs. The first 10 inputs are read; a longer list, up to 100, returns the rest unread in deferred_companies."
},
"period_type": {
"enum": [
"annual",
"quarterly"
],
"type": "string",
"default": "annual",
"description": "Align on fiscal years, each under the calendar-year key SEC frames it as (annual), or on calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats."
}
},
"additionalProperties": false
}secedgar_compare_companies output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"period_type",
"taxonomy",
"periods",
"companies",
"failed_companies",
"concepts",
"cells",
"gaps",
"unknown_concepts",
"caveats"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The periods cap applied."
},
"gaps": {
"type": "array",
"items": {
"type": "object",
"required": [
"cik",
"company",
"concept",
"tags_tried"
],
"properties": {
"cik": {
"type": "string",
"description": "Company CIK that reports nothing for this concept."
},
"company": {
"type": "string",
"description": "Company name."
},
"concept": {
"type": "string",
"description": "Concept with no value for this company."
},
"tags_tried": {
"type": "array",
"items": {
"type": "string"
},
"description": "XBRL tags attempted, in priority order, before giving up."
}
},
"description": "One company-concept pair with no reported value.",
"additionalProperties": false
},
"description": "Company-concept pairs with no value in any period, never zero-filled; a pair with values only before the inline window is in caveats instead."
},
"cells": {
"type": "array",
"items": {
"type": "object",
"required": [
"cik",
"company",
"concept",
"period",
"value",
"unit",
"taxonomy",
"tag",
"frame",
"period_end",
"form",
"accession_number"
],
"properties": {
"cik": {
"type": "string",
"description": "Company CIK, zero-padded to 10 digits."
},
"tag": {
"type": "string",
"description": "XBRL tag this value was reported under; can differ between periods of one company."
},
"form": {
"type": "string",
"description": "Source filing type (10-K, 10-Q, 20-F)."
},
"unit": {
"type": "string",
"description": "Unit of measure for this value."
},
"frame": {
"type": "string",
"description": "Underlying XBRL frame; differs from period for point-in-time concepts (CY2024Q3I under CY2024)."
},
"value": {
"type": "number",
"description": "Reported value."
},
"period": {
"type": "string",
"description": "Aligned calendar period key (e.g. \"CY2024\", \"CY2024Q2\")."
},
"company": {
"type": "string",
"description": "Company name."
},
"concept": {
"type": "string",
"description": "Concept the value belongs to."
},
"taxonomy": {
"type": "string",
"description": "Taxonomy the value was read from."
},
"period_end": {
"type": "string",
"description": "Period end date (YYYY-MM-DD); differs across off-calendar filers in one aligned period."
},
"accession_number": {
"type": "string",
"description": "Source filing accession number — pass to secedgar_get_filing."
}
},
"description": "One company-concept-period value.",
"additionalProperties": false
},
"description": "Inline matrix values, covering the periods listed in periods[]."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"no_companies_resolved",
"no_comparable_data",
"unknown_concept",
"rate_limited",
"sec_unreachable"
],
"description": "Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the company inputs read resolved to a CIK; inputs past the caps were not read and are named in deferred_companies and deferred_concepts. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type; any company or concept inputs past the caps are named, unread, in deferred_companies and deferred_concepts. `unknown_concept`: Every requested concept is neither a supported friendly name nor shaped like an XBRL tag, so no request is sent. `rate_limited`: SEC is rate-limiting this server's IP — SEC answered 429, or the call was refused without being sent while the cool-down after one runs. `sec_unreachable`: SEC EDGAR gave no complete, readable response — on the last attempt made (the third, or an earlier one once this call's 40-second budget for SEC failures ran out) the connection failed, no response headers arrived within 15 seconds, or the body broke off or stalled for 15 seconds, each wait capped at what was left of that budget; a 200 body was not the JSON SEC serves; or earlier SEC failures had spent that budget, so the request was never sent. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of periods shown inline."
},
"notice": {
"type": "string",
"description": "Guidance on deferred inputs, periods the inline matrix dropped, or the staged dataframe."
},
"caveats": {
"type": "array",
"items": {
"type": "string"
},
"description": "Comparability warnings (company ones prefixed with the name): missing quarters; a concept 2+ years behind the company's other lines; an instant with no fiscal-year-end value (annual); differing period ends or units; values only before the inline window; merged inputs."
},
"dataset": {
"type": "object",
"required": [
"name",
"row_count",
"expires_at"
],
"properties": {
"name": {
"type": "string",
"description": "Dataframe handle (df_XXXXX_XXXXX) for secedgar_dataframe_describe, then secedgar_dataframe_query."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp."
}
},
"description": "Dataframe of the full aligned series, every period, with cells[] columns. Absent when canvas is unavailable.",
"additionalProperties": false
},
"periods": {
"type": "array",
"items": {
"type": "string"
},
"description": "Inline period keys, newest first; fewer than requested when the cell count shrank the window (see notice)."
},
"concepts": {
"type": "array",
"items": {
"type": "object",
"required": [
"concept",
"label",
"units"
],
"properties": {
"label": {
"type": "string",
"description": "Human-readable concept label."
},
"units": {
"type": "array",
"items": {
"type": "string"
},
"description": "Units this concept resolved to across companies; more than one means values are not directly comparable."
},
"concept": {
"type": "string",
"description": "Concept as supplied — friendly name or raw XBRL tag."
}
},
"description": "One requested concept and the units it resolved to.",
"additionalProperties": false
},
"description": "Concepts covered, in input order; spellings of one concept appear once, under the first."
},
"taxonomy": {
"type": "string",
"description": "Taxonomy the concepts were resolved under, echoed from input."
},
"companies": {
"type": "array",
"items": {
"type": "object",
"required": [
"input",
"cik",
"name"
],
"properties": {
"cik": {
"type": "string",
"description": "Resolved CIK, zero-padded to 10 digits."
},
"name": {
"type": "string",
"description": "Resolved entity name (SEC-conformed)."
},
"input": {
"type": "string",
"description": "The company string as supplied."
},
"ticker": {
"type": "string",
"description": "Ticker symbol when SEC lists one."
}
},
"description": "One company that contributed to the matrix.",
"additionalProperties": false
},
"description": "Companies included in the comparison."
},
"truncated": {
"type": "boolean",
"description": "True when the aligned series has more periods than the inline matrix shows."
},
"period_type": {
"type": "string",
"description": "Period alignment used, echoed from input."
},
"failed_companies": {
"type": "array",
"items": {
"type": "object",
"required": [
"input",
"reason",
"message"
],
"properties": {
"input": {
"type": "string",
"description": "The company string as supplied."
},
"reason": {
"enum": [
"not_found",
"ambiguous",
"no_company_facts"
],
"type": "string",
"description": "not_found: no CIK matched. ambiguous: several matched; the message lists up to 10. no_company_facts: resolved, but the filer reports no XBRL. Match on this, not the message."
},
"message": {
"type": "string",
"description": "What went wrong and how to fix this one input."
}
},
"description": "One company that could not be included.",
"additionalProperties": false
},
"description": "Companies excluded from the matrix; the rest still compare."
},
"unknown_concepts": {
"type": "array",
"items": {
"type": "object",
"required": [
"concept",
"suggestions"
],
"properties": {
"concept": {
"type": "string",
"description": "Concept as supplied, trimmed."
},
"derivation": {
"type": "string",
"description": "Formula over supported concepts, when it is a standard combination (e.g., \"operating_cash_flow − capex\")."
},
"suggestions": {
"type": "array",
"items": {
"type": "string"
},
"description": "Up to three closest supported friendly names. Empty when a derivation applies or no name is close."
}
},
"description": "One concept not queried for any company.",
"additionalProperties": false
},
"description": "Concepts neither a supported name nor an XBRL tag, reported once rather than as per-company gaps; secedgar_search_concepts lists the supported names."
},
"deferred_concepts": {
"type": "array",
"items": {
"type": "string"
},
"description": "Inputs naming a concept past the first 8 distinct, unread, as supplied."
},
"deferred_companies": {
"type": "array",
"items": {
"type": "string"
},
"description": "Company inputs past the first 10, unread, as supplied."
}
},
"additionalProperties": false
}secedgar_compare_companies annotations
{
"readOnlyHint": true,
"openWorldHint": true,
"idempotentHint": true
}secedgar_search_concepts — Secedgar Search Concepts
Advertised read-only
Search supported XBRL financial concepts by keyword, statement group, or taxonomy. Use before secedgar_get_financials, secedgar_compare_companies, or secedgar_fetch_frames to discover the right friendly name, or pass a raw XBRL tag (e.g., "NetIncomeLoss") to reverse-lookup which friendly names map to it. Empty search with no filters returns the full catalog.
secedgar_search_concepts input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"group": {
"enum": [
"income_statement",
"balance_sheet",
"cash_flow",
"per_share",
"entity_info"
],
"type": "string",
"description": "Filter to a single financial statement group. income_statement covers P&L items; balance_sheet covers position items (use instant periods in secedgar_fetch_frames); cash_flow covers CF statement items; per_share covers EPS and the diluted share count it divides by; entity_info covers DEI items like shares outstanding."
},
"search": {
"type": "string",
"description": "Case-insensitive substring matched against friendly name, label, and XBRL tags. Examples: \"cash\" finds cash and operating_cash_flow; \"earnings\" finds eps_basic and eps_diluted; \"NetIncomeLoss\" reverse-maps to net_income. Omit to list all concepts."
},
"taxonomy": {
"enum": [
"us-gaap",
"ifrs-full",
"dei"
],
"type": "string",
"description": "Filter to a single XBRL taxonomy. us-gaap for US filers, ifrs-full for foreign filers, dei for entity info."
}
},
"additionalProperties": false
}secedgar_search_concepts output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"total",
"concepts"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"description": "Machine-readable failure mode."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"total": {
"type": "number",
"description": "Number of concepts matching the filters."
},
"notice": {
"type": "string",
"description": "Guidance when no concepts matched — echoes the search term and suggests alternatives."
},
"concepts": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"label",
"tags",
"taxonomy",
"unit",
"group"
],
"properties": {
"name": {
"type": "string",
"description": "Friendly name to pass as `concept` to secedgar_get_financials or secedgar_fetch_frames, or in `concepts` to secedgar_compare_companies."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "XBRL tags under us-gaap, tried in order; several cover historical renames (pre- and post-ASC 606 revenue), possibly a retired tag as last resort."
},
"unit": {
"type": "string",
"description": "Unit of measure (USD, USD/shares, shares, pure); secedgar_fetch_frames also takes the dashed form."
},
"group": {
"enum": [
"income_statement",
"balance_sheet",
"cash_flow",
"per_share",
"entity_info"
],
"type": "string",
"description": "Statement section: income_statement, balance_sheet, cash_flow, per_share, or entity_info."
},
"label": {
"type": "string",
"description": "Human-readable concept label."
},
"taxonomy": {
"enum": [
"us-gaap",
"ifrs-full",
"dei"
],
"type": "string",
"description": "XBRL taxonomy this concept lives in: us-gaap (US filers), ifrs-full (foreign filers), or dei (entity info)."
},
"ifrs_tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "Tags under taxonomy \"ifrs-full\", tried in order; a different element set from tags, each seen in a live 20-F. Absent when there is no IFRS equivalent."
},
"related_tags": {
"type": "array",
"items": {
"type": "object",
"required": [
"tag",
"note"
],
"properties": {
"tag": {
"type": "string",
"description": "Alternate-definition XBRL tag some filers use as their primary line."
},
"note": {
"type": "string",
"description": "How this tag differs in definition from the mapped tags."
}
},
"description": "One alternate-definition tag and the reason it differs.",
"additionalProperties": false
},
"description": "Alternate-definition tags (not synonyms) many filers report this metric under, as secedgar_fetch_frames flags them (e.g., cash including restricted cash). Query them separately, never blindly unioned. Absent when none is known."
}
},
"description": "One XBRL concept mapping with its friendly name, tags, and grouping.",
"additionalProperties": false
},
"description": "Matching concepts, ordered by group then alphabetical by name."
}
},
"additionalProperties": false
}secedgar_search_concepts annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}secedgar_dataframe_describe — Secedgar Dataframe Describe
Advertised read-only
List the dataframes (df_XXXXX_XXXXX) registered by the data-returning secedgar_* tools — any tool whose response carries a `dataset` handle stages its full result set here. Each entry surfaces source tool, query parameters, creation/expiry timestamps, row count, column schema, and whether the dataframe is truncated relative to the upstream source. Read the column schema here before writing SQL for secedgar_dataframe_query.
secedgar_dataframe_describe input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"name": {
"type": "string",
"description": "Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all dataframes."
}
},
"additionalProperties": false
}secedgar_dataframe_describe output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataframes"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"canvas_unavailable"
],
"description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: The DataCanvas service is not configured for this deployment. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"dataframes": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"source_tool",
"query_params",
"created_at",
"expires_at",
"row_count",
"truncated",
"column_schema"
],
"properties": {
"name": {
"type": "string",
"description": "Canvas table name (df_XXXXX_XXXXX)."
},
"max_rows": {
"type": "number",
"description": "Materialization cap that produced `truncated`, when applicable."
},
"row_count": {
"type": "number",
"description": "Rows materialized in the dataframe."
},
"truncated": {
"type": "boolean",
"description": "True when the upstream source had more rows than were materialized."
},
"created_at": {
"type": "string",
"description": "ISO 8601 creation timestamp."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp, fixed when the table is staged; queries do not extend it."
},
"source_tool": {
"type": "string",
"description": "Tool that produced this dataframe."
},
"query_params": {
"type": "object",
"description": "Input parameters the source tool was called with.",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"column_schema": {
"type": "array",
"items": {
"type": "object",
"required": [
"name",
"type",
"nullable"
],
"properties": {
"name": {
"type": "string",
"description": "Column name."
},
"type": {
"type": "string",
"description": "Canvas column type (VARCHAR, BIGINT, DOUBLE, ...)."
},
"nullable": {
"type": "boolean",
"description": "Whether the column permits NULL."
}
},
"description": "One column declaration in the dataframe schema.",
"additionalProperties": false
},
"description": "Resolved column schema (all SEC dataframe columns are nullable)."
}
},
"description": "Provenance and schema for one dataframe.",
"additionalProperties": false
},
"description": "Active dataframes for this tenant, newest first. Empty when none are registered."
}
},
"additionalProperties": false
}secedgar_dataframe_describe annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}secedgar_dataframe_query — Secedgar Dataframe Query
Advertised read-only
Run a single-statement SELECT against the canvas dataframes registered by the data-returning secedgar_* tools — any tool whose response carries a `dataset` handle. Inspect a dataframe with secedgar_dataframe_describe first; its column schema is what the SQL has to match. Read-only: writes, DDL, DROP, COPY, PRAGMA, ATTACH, and external-file table functions are rejected. System catalogs (information_schema, pg_catalog, sqlite_master, duckdb_*) are denied — list dataframes via secedgar_dataframe_describe. Optional register_as chains the result as a new dataframe with a fresh TTL.
secedgar_dataframe_query input schema
{
"type": "object",
"$schema": "https://json-schema.org/draft/2020-12/schema",
"required": [
"sql"
],
"properties": {
"sql": {
"type": "string",
"minLength": 1,
"description": "Single-statement SELECT against df_<id> tables on the shared canvas. Standard DuckDB SQL — joins, aggregates, window functions, CTEs all supported. Reference dataframes by the names returned in fetch/search responses or listed by secedgar_dataframe_describe. BIGINT columns (e.g., XBRL `value`, COUNT/SUM results) serialize as JSON strings to preserve precision past 2^53 — CAST(col AS DOUBLE) in projections for inline arithmetic."
},
"preview": {
"type": "integer",
"maximum": 100000,
"minimum": 0,
"description": "Rows to include in the immediate response. Defaults to the row limit. Set lower (e.g., 50) when chaining via register_as and only a sample is needed inline. Capped at 10000: a larger value, up to 100000, returns what 10000 returns."
},
"row_limit": {
"type": "integer",
"default": 1000,
"maximum": 100000,
"minimum": 1,
"description": "Hard cap on rows materialized in the response. Default 1000. A query matching more rows than this stops at the cap and `row_count_capped` comes back true; the full result lives on-canvas under register_as when provided, so do not raise this to keep large results. One case is not detectable: a SQL LIMIT exactly equal to this cap reads identically to a result that genuinely holds that many rows, and is reported as exact. Capped at 10000: a larger value, up to 100000, returns what 10000 returns."
},
"register_as": {
"type": "string",
"pattern": "^df_[A-Z0-9]{5}_[A-Z0-9]{5}$",
"description": "When set, persist the result as a new dataframe under this name (must match df_XXXXX_XXXXX shape, or pass a fresh df_<id> generated by the agent). Fresh TTL window — not inherited from the parents in the SELECT. Use to chain analyses without re-running the source SQL."
}
},
"additionalProperties": false
}secedgar_dataframe_query output schema
{
"type": "object",
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"columns",
"row_count",
"row_count_capped",
"rows"
]
},
{
"required": [
"error"
]
}
],
"$schema": "https://json-schema.org/draft/2020-12/schema",
"properties": {
"cap": {
"type": "number",
"description": "The row cap that actually bound — `preview` when it is lower than `row_limit`, otherwise `row_limit`."
},
"rows": {
"type": "array",
"items": {
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"description": "Materialized rows, bounded by `preview` / `row_limit`."
},
"error": {
"type": "object",
"required": [
"code",
"message"
],
"properties": {
"code": {
"type": "integer",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"description": "JSON-RPC error code for this failure."
},
"data": {
"type": "object",
"properties": {
"reason": {
"type": "string",
"examples": [
"canvas_unavailable",
"system_catalog_access",
"missing_table",
"invalid_sql",
"sql_execution_error",
"register_as_clash",
"non_select_statement",
"multi_statement",
"denied_function",
"sql_read_only",
"plan_operator_not_allowed"
],
"description": "Machine-readable failure mode. Declared by this tool: `canvas_unavailable`: The DataCanvas service is not configured for this deployment. `system_catalog_access`: The SQL query references a denied DuckDB system catalog (information_schema, pg_catalog, sqlite_master, duckdb_*). `missing_table`: The SQL query references a df_<id> table that does not exist or has expired. `invalid_sql`: The SELECT fails to prepare — an unknown column or an invalid expression — or hits an engine error no more specific reason covers. `sql_execution_error`: The SELECT prepared but failed on the data it read — a cast or conversion that does not fit, an out-of-range value, or invalid input to a function. `register_as_clash`: The register_as target name already exists on the canvas. `non_select_statement`: The SQL is not a SELECT (DROP, INSERT, UPDATE, DDL, PRAGMA, EXPLAIN, etc.) or does not parse — only read-only SELECTs run against dataframes. `multi_statement`: The SQL holds more than one statement. `denied_function`: The SQL calls a file-reading or external-data table function (read_csv, read_parquet, glob), a function that reads an engine setting (current_setting, current_schema — an unqualified current_schema is refused even where it names a column, which reads qualified as <table>.current_schema), or one that runs SQL or names a table from a string (query_table, or query() over anything but a single string literal). `sql_read_only`: The SQL names a file as a table (FROM 'data.csv') — the dataframe engine reads no files. `plan_operator_not_allowed`: The query plan uses an operator outside the read-only allowlist, such as the range() or generate_series() table functions. Other values are possible when a failure originates below the handler."
},
"recovery": {
"type": "object",
"required": [
"hint"
],
"properties": {
"hint": {
"type": "string"
}
},
"description": "Actionable next step for the caller.",
"additionalProperties": {}
},
"retryable": {
"type": "boolean",
"description": "Whether retrying may succeed."
}
},
"additionalProperties": {}
},
"message": {
"type": "string",
"description": "Human-readable description of what went wrong."
}
},
"description": "Present when the call failed. Absent on success.",
"additionalProperties": {}
},
"shown": {
"type": "number",
"description": "Number of rows returned inline."
},
"notice": {
"type": "string",
"description": "Guidance when the query returned no rows, or when the row cap withheld some."
},
"columns": {
"type": "array",
"items": {
"type": "string"
},
"description": "Column names in projection order."
},
"row_count": {
"type": "number",
"description": "Rows the query produced, up to `row_limit`; exceeds `rows.length` when `preview` returned fewer. When `row_count_capped` is true this is the cap, not the full size."
},
"truncated": {
"type": "boolean",
"description": "True when the result set held more rows than the row cap allowed through."
},
"expires_at": {
"type": "string",
"description": "ISO 8601 expiry timestamp for the newly registered dataframe, when applicable."
},
"registered_as": {
"type": "string",
"description": "Set when `register_as` was supplied and the new dataframe was materialized."
},
"row_count_capped": {
"type": "boolean",
"description": "True when more rows matched than `row_limit`, so `row_count` is the cap; false means `row_count` is exact."
}
},
"additionalProperties": false
}secedgar_dataframe_query annotations
{
"readOnlyHint": true,
"openWorldHint": false,
"idempotentHint": true
}Prompts
1 advertised
secedgar_company_analysis
Guide a structured analysis of a public company's SEC filings: identify recent filings, extract financial trends, surface risk factors, and note material events.
- company
- Company name, ticker symbol, or CIK number to analyze. (required)
- focus_areas
- Specific areas to focus on (e.g., "revenue growth, debt levels, insider activity"). If omitted, performs a general analysis.
Resources
3 advertised
XBRL Financial Concepts — XBRL Financial Concepts
Reference list of common XBRL financial concepts grouped by financial statement, mapping friendly names accepted by secedgar_get_financials, secedgar_compare_companies, and secedgar_fetch_frames to their XBRL tags.
XBRL Financial Concepts URI
secedgar://conceptsSEC Filing Types — SEC Filing Types
Reference list of common SEC filing types with descriptions, cadence, and typical use cases, plus the full 8-K item-code decode tables for both numbering regimes. Helps choose the forms parameter for secedgar_search_filings and secedgar_company_search, or the items filter for secedgar_get_material_events.
SEC Filing Types URI
secedgar://filing-typessecedgar-guide
Route SEC EDGAR research across the secedgar_* tools — which ownership tool answers each who-holds-what question, where CIKs, accession numbers, CUSIPs, fund series IDs, and filer CIKs come from, how XBRL period keys relate to fiscal years, and the coverage limits to check before calling a filing, figure, or holder absent. Use when answering questions about a company's SEC filings, financials, insiders, institutional or 5% holders, or fund portfolios with secedgar_* tools.
secedgar-guide URI
skill://secedgar-guide/SKILL.mdio.modelcontextprotocol/skills
io.modelcontextprotocol/skills URI template
skill://{+path}90-day uptime
A lightweight connection check about every six hours, sampled on hosts with many listings. It shows the server answered, not that its tools work.
- 2026-11-07: 1 of 1 checks answered
30-day availability
Aggregated from read-only remote checks; this is not a tool-execution or security guarantee.
- Successful checks
- 1 of 1 (100%)
- Average latency
- 680 ms
- 95th percentile latency
- 680 ms
Maintenance history
Public check and source-refresh events. Editorial and ownership records remain private.
- · probe · passed · 680 ms · metadata changed · 16 tool(s), 3 resource(s), 1 resource template(s), 1 prompt(s)
Connect from your client
Each snippet registers the same endpoint; pick the client you use.
Claude Code
Claude Code configuration
claude mcp add --transport http secedgar-mcp-server-caseyjhand https://secedgar.caseyjhand.com/mcpCodex
Codex configuration
codex mcp add secedgar-mcp-server-caseyjhand --url https://secedgar.caseyjhand.com/mcpCursor
Cursor configuration
{
"mcpServers": {
"secedgar-mcp-server-caseyjhand": {
"url": "https://secedgar.caseyjhand.com/mcp"
}
}
}Cline
Cline configuration
{
"mcpServers": {
"secedgar-mcp-server-caseyjhand": {
"type": "streamableHttp",
"url": "https://secedgar.caseyjhand.com/mcp",
"disabled": false
}
}
}VS Code
VS Code configuration
{
"servers": {
"secedgar-mcp-server-caseyjhand": {
"type": "http",
"url": "https://secedgar.caseyjhand.com/mcp"
}
}
}Gemini CLI
Gemini CLI configuration
gemini mcp add --transport http secedgar-mcp-server-caseyjhand https://secedgar.caseyjhand.com/mcpClaude Desktop
Claude Desktop configuration
https://secedgar.caseyjhand.com/mcpWindsurf
Windsurf configuration
{
"mcpServers": {
"secedgar-mcp-server-caseyjhand": {
"serverUrl": "https://secedgar.caseyjhand.com/mcp"
}
}
}Let your agent find its tools
Find servers like secedgar-mcp-server from your agent. Add Koskamo once to search the index for endpoints, access requirements, and client setup. Public discovery needs no key.