Server definition
- Hash
- sha256:fc0e076e6f28c384756c2effa15f06a17ae9d9d5bcc76d470f27d3bac05a64cd
- What it is
- What a remote MCP server returned when asked what it offers: 16 tools
The blob, as servednamed by its sha256
{
"instructions": "Resolve a company with secedgar_company_search (ticker, name, or CIK), find its filings with secedgar_search_filings — full text covers 2001 onward, while earlier ranges browse the archives by form and need ticker:/cik: scope for text matching — and read one by accession number with secedgar_get_filing. Financial tools take friendly concept names such as \"revenue\" or \"eps_diluted\" (list them with secedgar_search_concepts), and ownership runs both ways: a 13F manager to its portfolio, an issuer to its institutional holders or 5%-and-over blockholders, a fund to its NPORT-P holdings. Data-returning tools also stage their full result as a df_<id> dataframe — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"tools": [
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"filed_after": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"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": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"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": {
"default": 10,
"description": "Maximum number of filings to return in the inline list.",
"maximum": 50,
"minimum": 1,
"type": "integer"
},
"forms": {
"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.",
"items": {
"type": "string"
},
"type": "array"
},
"include_filings": {
"default": true,
"description": "Include recent filings in the response. Set to false for entity-info-only lookups.",
"type": "boolean"
},
"query": {
"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, and the corporate suffix does not have to match the registry's form (\"Beacon Financial Corporation\" finds \"Beacon Financial Corp\") — but Corp, Inc, Co, and Ltd stay distinct from each other, since separate registrants differ only by which one they use.",
"minLength": 1,
"type": "string"
}
},
"required": [
"query"
],
"type": "object"
},
"name": "secedgar_company_search",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"cik",
"name",
"tickers",
"exchanges",
"sic",
"sic_description"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The `filing_limit` that was applied.",
"type": "number"
},
"cik": {
"description": "Central Index Key, zero-padded to 10 digits.",
"type": "string"
},
"class_id": {
"description": "SEC fund class ID (e.g. \"C000092055\"). Present when the query resolved via a fund ticker (ETF or mutual fund).",
"type": "string"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding the full filtered filing history (recent + archive pages), registered only when the scan reached beyond the recent window and the history exceeds filing_limit. Query the complete history — filings by form by year — with secedgar_dataframe_query; the inline `filings` list stays capped at filing_limit.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
},
"truncated": {
"description": "True when the archive scan hit its page cap before exhausting the manifest — older matching filings exist beyond the dataframe.",
"type": "boolean"
}
},
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_match`: No company matches the query. `multiple_matches`: Query is ambiguous and matches several companies. `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. Other values are possible when a failure originates below the handler.",
"examples": [
"no_match",
"multiple_matches",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"exchanges": {
"description": "Exchanges where listed.",
"items": {
"type": "string"
},
"type": "array"
},
"filings": {
"description": "Recent filings, filtered by forms if specified.",
"items": {
"additionalProperties": false,
"description": "One filing record with form type, dates, and primary document.",
"properties": {
"accession_number": {
"description": "Filing accession number, dash format (e.g., 0000320193-23-000106). Pass to secedgar_get_filing.",
"type": "string"
},
"description": {
"description": "SEC-provided filing description. Absent when SEC published none.",
"type": "string"
},
"filing_date": {
"description": "Date the filing was submitted (YYYY-MM-DD).",
"type": "string"
},
"form": {
"description": "Form type (e.g., 10-K).",
"type": "string"
},
"primary_document": {
"description": "Primary document filename.",
"type": "string"
},
"report_date": {
"description": "Period of report (YYYY-MM-DD). Absent for filings without a reporting period (proxy statements, ownership reports).",
"type": "string"
}
},
"required": [
"accession_number",
"form",
"filing_date",
"primary_document"
],
"type": "object"
},
"type": "array"
},
"fiscal_year_end": {
"description": "Fiscal year end (MM-DD format, e.g., \"09-26\"). Absent for filers SEC records no fiscal year end for (e.g. private or pre-IPO entities).",
"type": "string"
},
"history_scanned_through": {
"description": "Oldest filing date reached by the scan (YYYY-MM-DD). Filings older than this were not examined: the recent window holds the last year or 1,000 filings, whichever is more, and older filings live in archive pages fetched only when a date filter or an under-filled form filter requires them. Absent when no filings were scanned.",
"type": "string"
},
"name": {
"description": "SEC-conformed company name.",
"type": "string"
},
"notice": {
"description": "Guidance when include_filings=true but no filings matched the forms filter, or when filing_limit withheld some.",
"type": "string"
},
"series_id": {
"description": "SEC fund series ID (e.g. \"S000002839\"). Present when the query resolved via a fund ticker (ETF or mutual fund).",
"type": "string"
},
"shown": {
"description": "Number of filings returned inline.",
"type": "number"
},
"sic": {
"description": "SIC industry code.",
"type": "string"
},
"sic_description": {
"description": "Human-readable SIC description.",
"type": "string"
},
"state_of_incorporation": {
"description": "State of incorporation (US two-letter code, e.g. \"DE\"). Omitted for some entities, including many foreign filers and individuals.",
"type": "string"
},
"tickers": {
"description": "Associated ticker symbols.",
"items": {
"type": "string"
},
"type": "array"
},
"total_filings": {
"description": "Total filings matching the filter across everything scanned (recent window + any archive pages), which may exceed filing_limit and the inline list.",
"type": "number"
},
"truncated": {
"description": "True when more filings matched than `filing_limit` allowed into the inline list.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Compare 2-10 named companies across 1-8 XBRL concepts, aligned on calendar periods. 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 and align on the calendar year (annual) or quarter (quarterly) their snapshot falls in, so they sit in the same matrix as income-statement lines. 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 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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"companies": {
"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.",
"items": {
"description": "Ticker symbol or CIK number.",
"minLength": 1,
"type": "string"
},
"maxItems": 10,
"minItems": 2,
"type": "array"
},
"concepts": {
"description": "Concepts to compare — friendly names like \"revenue\" or \"net_income\" (discover them with secedgar_search_concepts) or raw XBRL tags.",
"items": {
"description": "Friendly concept name or raw XBRL tag.",
"minLength": 1,
"type": "string"
},
"maxItems": 8,
"minItems": 1,
"type": "array"
},
"period_type": {
"default": "annual",
"description": "Align on full calendar years (annual) or calendar quarters (quarterly). Quarterly comparisons of off-calendar filers are missing at least one calendar quarter per year — see caveats.",
"enum": [
"annual",
"quarterly"
],
"type": "string"
},
"periods": {
"default": 4,
"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.",
"maximum": 12,
"minimum": 1,
"type": "integer"
},
"taxonomy": {
"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.",
"enum": [
"us-gaap",
"ifrs-full"
],
"type": "string"
}
},
"required": [
"companies",
"concepts"
],
"type": "object"
},
"name": "secedgar_compare_companies",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"period_type",
"taxonomy",
"periods",
"companies",
"failed_companies",
"concepts",
"cells",
"gaps",
"unknown_concepts",
"caveats"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The periods cap applied.",
"type": "number"
},
"caveats": {
"description": "Comparability warnings: a filer missing one or two calendar quarters from the frame-tagged series, a concept whose values stop at least two full years behind the rest of that company's reporting (either an XBRL tag SEC has retired, or a current tag the filer stopped using), period ends that differ inside one aligned period, concepts whose unit differs across companies, and — one line per concept — the companies that report a concept but have no value inside the inline periods, each with its newest period (its values are in the dataframe), and the concept inputs merged because they name the same concept. Company-specific warnings are prefixed with the company name. Empty when nothing needs flagging.",
"items": {
"type": "string"
},
"type": "array"
},
"cells": {
"description": "Inline matrix values, covering the periods listed in periods[].",
"items": {
"additionalProperties": false,
"description": "One company-concept-period value.",
"properties": {
"accession_number": {
"description": "Source filing accession number — pass to secedgar_get_filing.",
"type": "string"
},
"cik": {
"description": "Company CIK, zero-padded to 10 digits.",
"type": "string"
},
"company": {
"description": "Company name.",
"type": "string"
},
"concept": {
"description": "Concept the value belongs to.",
"type": "string"
},
"form": {
"description": "Source filing type (10-K, 10-Q, 20-F).",
"type": "string"
},
"frame": {
"description": "Underlying XBRL frame, which differs from period for point-in-time concepts (e.g. frame CY2024Q3I under period CY2024).",
"type": "string"
},
"period": {
"description": "Aligned calendar period key (e.g. \"CY2024\", \"CY2024Q2\").",
"type": "string"
},
"period_end": {
"description": "Period end date (YYYY-MM-DD). Differs across off-calendar filers within one aligned period.",
"type": "string"
},
"tag": {
"description": "XBRL tag this value was reported under — one concept can walk several tags, so it can differ between periods of the same company.",
"type": "string"
},
"taxonomy": {
"description": "Taxonomy the value was read from.",
"type": "string"
},
"unit": {
"description": "Unit of measure for this value.",
"type": "string"
},
"value": {
"description": "Reported value.",
"type": "number"
}
},
"required": [
"cik",
"company",
"concept",
"period",
"value",
"unit",
"taxonomy",
"tag",
"frame",
"period_end",
"form",
"accession_number"
],
"type": "object"
},
"type": "array"
},
"companies": {
"description": "Companies included in the comparison.",
"items": {
"additionalProperties": false,
"description": "One company that resolved and contributed to the matrix.",
"properties": {
"cik": {
"description": "Resolved CIK, zero-padded to 10 digits.",
"type": "string"
},
"input": {
"description": "The company string as supplied.",
"type": "string"
},
"name": {
"description": "Resolved entity name (SEC-conformed).",
"type": "string"
},
"ticker": {
"description": "Ticker symbol when SEC lists one.",
"type": "string"
}
},
"required": [
"input",
"cik",
"name"
],
"type": "object"
},
"type": "array"
},
"concepts": {
"description": "Concepts covered, in the order supplied. Inputs that name the same concept (revenue and Revenue, or one raw tag spelled twice) appear once, under the first spelling.",
"items": {
"additionalProperties": false,
"description": "One requested concept and the units it resolved to.",
"properties": {
"concept": {
"description": "Concept as supplied — friendly name or raw XBRL tag.",
"type": "string"
},
"label": {
"description": "Human-readable concept label.",
"type": "string"
},
"units": {
"description": "Distinct units this concept resolved to across the companies. More than one means the values are not directly comparable — see caveats.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"concept",
"label",
"units"
],
"type": "object"
},
"type": "array"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding the full aligned series across every period, not just the inline window. Columns match cells[]. Absent when canvas is unavailable.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
}
},
"required": [
"name",
"row_count",
"expires_at"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_companies_resolved`: None of the supplied company inputs resolved to a CIK. `no_comparable_data`: Companies resolved but not one of them reports any of the requested concepts for the requested period type. `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. Other values are possible when a failure originates below the handler.",
"examples": [
"no_companies_resolved",
"no_comparable_data",
"unknown_concept",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"failed_companies": {
"description": "Companies excluded from the matrix. The comparison proceeds with the rest rather than failing the whole call.",
"items": {
"additionalProperties": false,
"description": "One company that could not be included, with a machine-readable reason.",
"properties": {
"input": {
"description": "The company string as supplied.",
"type": "string"
},
"message": {
"description": "What went wrong and how to fix this one input.",
"type": "string"
},
"reason": {
"description": "Machine-readable failure. not_found: the input matched no CIK. ambiguous: it matched several, and the message lists them. no_company_facts: it resolved but the filer reports no XBRL. Match on this rather than the message.",
"enum": [
"not_found",
"ambiguous",
"no_company_facts"
],
"type": "string"
}
},
"required": [
"input",
"reason",
"message"
],
"type": "object"
},
"type": "array"
},
"gaps": {
"description": "Company-concept pairs with no value in any period. Deliberately explicit — a missing value is never interpolated or zero-filled. A pair with values only in periods older than the inline window is not a gap; caveats names it.",
"items": {
"additionalProperties": false,
"description": "One company-concept pair with no reported value.",
"properties": {
"cik": {
"description": "Company CIK that reports nothing for this concept.",
"type": "string"
},
"company": {
"description": "Company name.",
"type": "string"
},
"concept": {
"description": "Concept with no value for this company.",
"type": "string"
},
"tags_tried": {
"description": "XBRL tags attempted, in priority order, before giving up.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"cik",
"company",
"concept",
"tags_tried"
],
"type": "object"
},
"type": "array"
},
"notice": {
"description": "Guidance when the inline matrix dropped periods, or when the full aligned series is staged as a dataframe.",
"type": "string"
},
"period_type": {
"description": "Period alignment used, echoed from input.",
"type": "string"
},
"periods": {
"description": "Calendar period keys covered by the inline matrix, newest first. Shorter than the requested periods when the cell count forced the window to shrink — the enrichment trailer reports the drop.",
"items": {
"type": "string"
},
"type": "array"
},
"shown": {
"description": "Number of periods shown inline.",
"type": "number"
},
"taxonomy": {
"description": "Taxonomy the concepts were resolved under, echoed from input.",
"type": "string"
},
"truncated": {
"description": "True when the aligned series has more periods than the inline matrix shows.",
"type": "boolean"
},
"unknown_concepts": {
"description": "Requested concepts that are neither a supported friendly name nor an XBRL tag (UpperCamelCase, e.g. NetIncomeLoss), reported once each rather than as a gap per company — secedgar_search_concepts lists every supported name. Empty when every concept resolved.",
"items": {
"additionalProperties": false,
"description": "One requested concept that was not queried for any company.",
"properties": {
"concept": {
"description": "Concept as supplied (trimmed) — neither a supported friendly name nor an XBRL tag.",
"type": "string"
},
"derivation": {
"description": "How to build it from supported concepts when it is a standard combination, e.g. \"operating_cash_flow − capex\".",
"type": "string"
},
"suggestions": {
"description": "Up to three closest supported friendly names. Empty when a derivation applies or no name is close.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"concept",
"suggestions"
],
"type": "object"
},
"type": "array"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"name": {
"description": "Optional table name (df_XXXXX_XXXXX) to describe a single dataframe. Omit to list all dataframes.",
"type": "string"
}
},
"type": "object"
},
"name": "secedgar_dataframe_describe",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"dataframes"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"dataframes": {
"description": "Active dataframes for this tenant, newest first. Empty when none are registered.",
"items": {
"additionalProperties": false,
"description": "Provenance and schema for one dataframe.",
"properties": {
"column_schema": {
"description": "Resolved column schema (all SEC dataframe columns are nullable).",
"items": {
"additionalProperties": false,
"description": "One column declaration in the dataframe schema.",
"properties": {
"name": {
"description": "Column name.",
"type": "string"
},
"nullable": {
"description": "Whether the column permits NULL.",
"type": "boolean"
},
"type": {
"description": "Canvas column type (VARCHAR, BIGINT, DOUBLE, ...).",
"type": "string"
}
},
"required": [
"name",
"type",
"nullable"
],
"type": "object"
},
"type": "array"
},
"created_at": {
"description": "ISO 8601 creation timestamp.",
"type": "string"
},
"expires_at": {
"description": "ISO 8601 expiry timestamp. Sliding TTL touched on every dataframe op.",
"type": "string"
},
"max_rows": {
"description": "Materialization cap that produced `truncated`, when applicable.",
"type": "number"
},
"name": {
"description": "Canvas table name (df_XXXXX_XXXXX).",
"type": "string"
},
"query_params": {
"additionalProperties": {},
"description": "Input parameters the source tool was called with.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
},
"source_tool": {
"description": "Tool that produced this dataframe.",
"type": "string"
},
"truncated": {
"description": "True when the upstream source had more rows than were materialized.",
"type": "boolean"
}
},
"required": [
"name",
"source_tool",
"query_params",
"created_at",
"expires_at",
"row_count",
"truncated",
"column_schema"
],
"type": "object"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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.",
"examples": [
"canvas_unavailable"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"preview": {
"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.",
"maximum": 10000,
"minimum": 0,
"type": "integer"
},
"register_as": {
"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.",
"pattern": "^df_[A-Z0-9]{5}_[A-Z0-9]{5}$",
"type": "string"
},
"row_limit": {
"default": 1000,
"description": "Hard cap on rows materialized in the response. Default 1000, max 10000. 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.",
"maximum": 10000,
"minimum": 1,
"type": "integer"
},
"sql": {
"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.",
"minLength": 1,
"type": "string"
}
},
"required": [
"sql"
],
"type": "object"
},
"name": "secedgar_dataframe_query",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"columns",
"row_count",
"row_count_capped",
"rows"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The row cap that actually bound — `preview` when it is lower than `row_limit`, otherwise `row_limit`.",
"type": "number"
},
"columns": {
"description": "Column names in projection order.",
"items": {
"type": "string"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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 such as read_csv, read_parquet, or glob. `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.",
"examples": [
"canvas_unavailable",
"system_catalog_access",
"missing_table",
"invalid_sql",
"sql_execution_error",
"register_as_clash",
"non_select_statement",
"multi_statement",
"denied_function",
"plan_operator_not_allowed"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"expires_at": {
"description": "ISO 8601 expiry timestamp for the newly registered dataframe, when applicable.",
"type": "string"
},
"notice": {
"description": "Guidance when the query returned no rows, or when the row cap withheld some.",
"type": "string"
},
"registered_as": {
"description": "Set when `register_as` was supplied and the new dataframe was materialized.",
"type": "string"
},
"row_count": {
"description": "Rows the query produced, up to `row_limit` (exceeds `rows.length` when `preview` returned fewer). Read it with `row_count_capped`: when that is true this number is the `row_limit` cap itself, and the size of the full result is not in this response.",
"type": "number"
},
"row_count_capped": {
"description": "True when the query matched more rows than `row_limit`, so `row_count` is that cap rather than a total. False means `row_count` is exact — including when it happens to equal `row_limit`.",
"type": "boolean"
},
"rows": {
"description": "Materialized rows, bounded by `preview` / `row_limit`.",
"items": {
"additionalProperties": {},
"propertyNames": {
"type": "string"
},
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of rows returned inline.",
"type": "number"
},
"truncated": {
"description": "True when the result set held more rows than the row cap allowed through.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"concept": {
"description": "Financial concept — same friendly names as secedgar_get_financials (e.g., \"revenue\", \"assets\", \"eps_basic\") or raw XBRL tag.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 25,
"description": "Number of companies to return.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 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.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"period": {
"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).",
"minLength": 1,
"pattern": "^CY\\d{4}(Q[1-4]I?)?$",
"type": "string"
},
"sort": {
"default": "desc",
"description": "Sort direction. \"desc\" for highest values first (typical for revenue, assets). \"asc\" for lowest values.",
"enum": [
"desc",
"asc"
],
"type": "string"
},
"taxonomy": {
"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.",
"enum": [
"us-gaap",
"dei"
],
"type": "string"
},
"unit": {
"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.",
"enum": [
"USD",
"USD-per-shares",
"USD/shares",
"shares",
"pure"
],
"type": "string"
}
},
"required": [
"concept",
"period"
],
"type": "object"
},
"name": "secedgar_fetch_frames",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"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"
]
}
],
"properties": {
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"caveats": {
"description": "Data-completeness warnings specific to this query. Populated for duration periods 'CY####Q[1-4]', where SEC XBRL omits filers' fiscal Q4 (reported only as the 10-K residual) — affected filers are silently absent from the frame. Populated for annual ('CY####') NetIncomeLoss frames, where a filer's row can be its proxy statement's pay-versus-performance figure rather than the 10-K's. Populated for an annual frame whose calendar year is still open or inside its 10-K filing window, where a filer's row can be a trailing-twelve-month figure from a 10-Q rather than a fiscal year. Also flags a value distribution whose top rows look like split or scale-factor artifacts. Otherwise empty.",
"items": {
"type": "string"
},
"type": "array"
},
"concept": {
"description": "XBRL tag the data was actually fetched against (after resolving any friendly name).",
"type": "string"
},
"data": {
"description": "Ranked companies for this metric.",
"items": {
"additionalProperties": false,
"description": "One company's reported value for this metric and period.",
"properties": {
"accession_number": {
"description": "Source filing for secedgar_get_filing.",
"type": "string"
},
"cik": {
"description": "Company CIK, zero-padded to 10 digits.",
"type": "string"
},
"company_name": {
"description": "Entity name.",
"type": "string"
},
"location": {
"description": "Business location (state or country). Absent when SEC has no location for this filer.",
"type": "string"
},
"period_end": {
"description": "Period end date (YYYY-MM-DD).",
"type": "string"
},
"rank": {
"description": "Rank in sorted order.",
"type": "number"
},
"ticker": {
"description": "Ticker symbol (if available).",
"type": "string"
},
"value": {
"description": "Reported value.",
"type": "number"
}
},
"required": [
"rank",
"company_name",
"cik",
"value",
"period_end",
"accession_number"
],
"type": "object"
},
"type": "array"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe handle holding the full frames response. Absent when canvas is unavailable or materialization failed.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
}
},
"required": [
"name",
"row_count",
"expires_at"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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 this metric 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. Other values are possible when a failure originates below the handler.",
"examples": [
"unknown_concept",
"no_data",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"label": {
"description": "Human-readable concept label.",
"type": "string"
},
"next_offset": {
"description": "Offset to pass on the next call to continue down the ranking. Absent on the last page (no companies remain past this one).",
"type": "number"
},
"notice": {
"description": "Guidance when the requested offset lands past the end of the ranked list.",
"type": "string"
},
"offset": {
"description": "Rank the returned page starts at, 0-based — the effective offset applied.",
"type": "number"
},
"period": {
"description": "Calendar period the data was fetched for, echoed from input.",
"type": "string"
},
"period_end_range": {
"additionalProperties": false,
"description": "Range of period_end dates across the frame. SEC normalizes to calendar periods but filers report against their own fiscal year-ends, so a \"CY2023\" duration frame can contain period_ends from 2023-01-31 (January-FY filers like Walmart) to 2024-12-31 (calendar-FY filers reported late). Wide ranges mean cross-comparison mixes fiscal periods.",
"properties": {
"max": {
"description": "Latest period_end across all rows (YYYY-MM-DD).",
"type": "string"
},
"min": {
"description": "Earliest period_end across all rows (YYYY-MM-DD).",
"type": "string"
}
},
"required": [
"min",
"max"
],
"type": "object"
},
"related_tags": {
"description": "Alternate-DEFINITION XBRL tags (distinct from same-meaning `unqueried_tags`) that a meaningful share of filers use as their primary line for this metric — e.g. `cash` filers reporting `CashCashEquivalentsRestrictedCashAndRestrictedCashEquivalents` (incl. restricted cash), `equity` filers reporting `StockholdersEquityIncludingPortionAttributableToNoncontrollingInterest` (incl. noncontrolling interest). These filers are NOT in `data` or the dataframe, so a whole-universe screen on the base tag silently under-counts. To recover them, run a separate fetch_frames against the alternate tag — do NOT blindly UNION (definitions differ; you would mix or double-count). Empty when the concept has no known high-coverage alternate.",
"items": {
"additionalProperties": false,
"description": "One alternate-definition tag and the reason it differs.",
"properties": {
"note": {
"description": "How this tag differs in definition from the queried tag.",
"type": "string"
},
"tag": {
"description": "Alternate XBRL tag a meaningful share of filers report this metric under instead.",
"type": "string"
}
},
"required": [
"tag",
"note"
],
"type": "object"
},
"type": "array"
},
"shown": {
"description": "Number of companies shown inline.",
"type": "number"
},
"taxonomy": {
"description": "Frames namespace the tag was read from (us-gaap or dei) — a friendly name mapped to dei reads dei under the us-gaap default.",
"type": "string"
},
"total_companies": {
"description": "Total companies reporting this metric for this period.",
"type": "number"
},
"truncated": {
"description": "True when the inline data[] was capped by limit.",
"type": "boolean"
},
"unit": {
"description": "Unit of measure used for the lookup (always normalized to dashed form, e.g. \"USD-per-shares\").",
"type": "string"
},
"unqueried_tags": {
"description": "Other same-meaning XBRL tags in the friendly-name mapping that this call did NOT query (historical/variant spellings of the same metric). Empty for raw tags or single-tag concepts — for alternate-DEFINITION tags some filers use instead, see `related_tags`. For \"revenue\" this typically lists `Revenues`, `SalesRevenueNet`, `SalesRevenueGoodsNet` — filers reporting under legacy variants are absent from `data`; call again per tag and UNION/COALESCE in SQL to recover them.",
"items": {
"type": "string"
},
"type": "array"
},
"value_distribution": {
"additionalProperties": false,
"description": "Distribution stats across the full frame, computed during materialization. Use `max_to_p95_ratio` as the primary outlier signal — it catches scale-factor anomalies even when median is 0 or negative.",
"properties": {
"max": {
"description": "Maximum reported value.",
"type": "number"
},
"max_to_p95_ratio": {
"description": "Maximum value divided by 95th percentile. Robust to zero/negative bulk (unlike median-based ratios — many frames have median = 0 or negative, e.g. EPS with many loss-making filers). Typical heavy-tail frames sit in the 10–50× range (mega-caps over the rest); ratios above ~200× usually indicate a filer-side XBRL scale-factor error (wrong `decimals` attribute) — verify the topmost row(s) in `data` before trusting absolute rankings.",
"type": "number"
},
"median": {
"description": "Median reported value across all reporters in the frame.",
"type": "number"
},
"p95": {
"description": "95th-percentile reported value.",
"type": "number"
}
},
"required": [
"median",
"p95",
"max",
"max_to_p95_ratio"
],
"type": "object"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"cusip": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "9-character CUSIP/CINS",
"pattern": "^[0-9A-Za-z]{9}$",
"type": "string"
}
],
"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."
},
"issuer": {
"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 is phrase-matched against 13F information tables, so it must identify one company. With cusip supplied, it is used only to label the result.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 20,
"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.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"quarter": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-QN",
"pattern": "^\\d{4}-Q[1-4]$",
"type": "string"
}
],
"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 nothing, because the filings do not exist yet."
}
},
"required": [
"issuer"
],
"type": "object"
},
"name": "secedgar_find_holders",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"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"
]
}
],
"properties": {
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding every fetched filer row, each carrying the issuer key and quarter so it joins across issuers and quarters. Absent when the result fits inline, canvas is unavailable, or materialization failed. Query with secedgar_dataframe_query.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
},
"truncated": {
"description": "True when more filers exist beyond the fetch budget — total_filings exceeds fetched.",
"type": "boolean"
}
},
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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. Other values are possible when a failure originates below the handler.",
"examples": [
"issuer_not_found",
"ambiguous_issuer",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"fetched": {
"description": "Filings retrieved from the index, capped by the fetch budget of 500. Equals total_filings when the whole window fit inside the budget.",
"type": "number"
},
"filed_from": {
"description": "Start of the filing window searched (YYYY-MM-DD).",
"type": "string"
},
"filed_to": {
"description": "End of the filing window searched (YYYY-MM-DD).",
"type": "string"
},
"holders": {
"description": "One page of filers, capped at limit. Order carries no position-size meaning — see the ordering note.",
"items": {
"additionalProperties": false,
"description": "One institutional manager reporting a position in this issuer.",
"properties": {
"accession_number": {
"description": "Accession number of the 13F-HR — pass to secedgar_get_filing.",
"type": "string"
},
"filer_cik": {
"description": "Filer CIK, zero-padded to 10 digits. Pass as company to secedgar_get_institutional_holdings for this manager's positions.",
"type": "string"
},
"filer_name": {
"description": "Institutional manager that filed, with ticker/CIK parentheticals stripped.",
"type": "string"
},
"filing_date": {
"description": "Date the 13F-HR was submitted (YYYY-MM-DD).",
"type": "string"
},
"form": {
"description": "Form type, \"13F-HR\" or \"13F-HR/A\" for an amendment. Absent when the index carries no form tag.",
"type": "string"
}
},
"required": [
"filer_name",
"filer_cik",
"accession_number",
"filing_date"
],
"type": "object"
},
"type": "array"
},
"holders_in_quarter": {
"description": "Distinct managers among the fetched filings reporting this quarter as their period — the set paged by limit and materialized on the dataframe. Lower than fetched by the filings dropped as amendments restating other quarters, and by managers that amended this quarter (kept once, at their latest filing).",
"type": "number"
},
"issuer": {
"description": "The issuer input, echoed.",
"type": "string"
},
"notice": {
"description": "Guidance when the search returned no filers — names the likely cause.",
"type": "string"
},
"ordering": {
"description": "How the holder list is ordered, and what that ordering does not mean.",
"type": "string"
},
"quarter": {
"description": "Reporting quarter searched, \"YYYY-QN\" — the requested one, or the applied default.",
"type": "string"
},
"resolved_issuer_cik": {
"description": "CIK of the resolved issuer, zero-padded to 10 digits. Absent when cusip was supplied.",
"type": "string"
},
"resolved_issuer_name": {
"description": "EDGAR-conformed company name the issuer resolved to, and the phrase that was searched. Absent when cusip was supplied (no company lookup runs).",
"type": "string"
},
"search_key": {
"description": "The exact term searched — the CUSIP, or the quoted phrase.",
"type": "string"
},
"search_mode": {
"description": "Which key matched the information tables. \"cusip\" matches the identifier the table itself carries; \"name\" phrase-matches the filing text and is looser in both directions.",
"enum": [
"cusip",
"name"
],
"type": "string"
},
"shown": {
"description": "Number of filers shown inline.",
"type": "number"
},
"total_filings": {
"description": "Total 13F-HR filings matching the search key inside the filing window, as reported by the index. A slight over-count of this quarter's holders on two counts, both of which the returned rows correct for: a few percent are amendments restating an older quarter, and a few more are managers amending their own report for this quarter, which puts them in the window twice.",
"type": "number"
},
"total_is_exact": {
"description": "False when total_filings is a lower bound (the index capped the count).",
"type": "boolean"
},
"truncated": {
"description": "True when the inline holders list was capped.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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 and 13F dataframes on issuer CIK — inspect it with secedgar_dataframe_describe, then analyze it with secedgar_dataframe_query.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"form_kind": {
"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.",
"enum": [
"all",
"13D",
"13G"
],
"type": "string"
},
"include_amendments": {
"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.",
"type": "boolean"
},
"issuer": {
"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.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 10,
"description": "Number of filings to fetch and parse, newest first. Each filing is a separate document fetch, so this is the cost of the call as well as its depth. Default 10; a widely-held company can have dozens of blockholder filings a year.",
"maximum": 20,
"minimum": 1,
"type": "integer"
}
},
"required": [
"issuer"
],
"type": "object"
},
"name": "secedgar_get_beneficial_owners",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"issuer",
"issuer_cik",
"issuer_name",
"form_kind",
"total_structured_filings",
"filings_parsed",
"structured_coverage_from",
"legacy_filings_before_coverage",
"filings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding one row per reporting person across every parsed filing, each row carrying the issuer, form, accession, and dates alongside the person's powers. Joins against the insider and 13F dataframes on issuer_cik. Absent when canvas is unavailable or nothing parsed.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
},
"truncated": {
"description": "True when the issuer has more structured filings than limit fetched — the dataframe holds the parsed filings only, not the whole history.",
"type": "boolean"
}
},
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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. Other values are possible when a failure originates below the handler.",
"examples": [
"issuer_not_found",
"ambiguous_issuer",
"no_filings_found",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"filings": {
"description": "Blockholder filings, newest first, capped at limit.",
"items": {
"additionalProperties": false,
"description": "One SCHEDULE 13D or 13G filing made about this issuer.",
"properties": {
"accession_number": {
"description": "Accession number — pass to secedgar_get_filing for the full document.",
"type": "string"
},
"amendment_number": {
"description": "Amendment sequence from the cover page. Absent on an original filing.",
"type": "string"
},
"cusips": {
"description": "CUSIPs of the subject class from the cover page. Empty when none listed.",
"items": {
"type": "string"
},
"type": "array"
},
"event_date": {
"description": "Date of the event that required the filing (YYYY-MM-DD) — when the position actually crossed or changed, which precedes filing_date. Absent when the cover page omits it.",
"type": "string"
},
"filing_date": {
"description": "Date the schedule was submitted (YYYY-MM-DD).",
"type": "string"
},
"form": {
"description": "EDGAR form name, e.g. \"SCHEDULE 13D\" or \"SCHEDULE 13G/A\".",
"type": "string"
},
"is_amendment": {
"description": "True when the form name carries the /A suffix.",
"type": "boolean"
},
"purpose_of_transaction": {
"description": "Item 4 purpose-of-transaction prose — what the holder says it intends. Present on 13D filings only; 13G has no such field, which is what makes it the passive form. Absent on an amendment that restates no purpose.",
"type": "string"
},
"purpose_truncated": {
"description": "True when purpose_of_transaction was clipped to fit — read the full item with secedgar_get_filing on this accession number.",
"type": "boolean"
},
"reporting_persons": {
"description": "Every reporting person on this filing. A joint filing lists a fund, its adviser, and its controlling principal separately, each reporting the same underlying shares.",
"items": {
"additionalProperties": false,
"description": "One reporting person from the schedule cover page.",
"properties": {
"aggregate_amount_owned": {
"description": "Shares beneficially owned by this person. Absent when the person reports no amount, which happens on an exit amendment reporting a zero position.",
"type": "number"
},
"cik": {
"description": "Reporting person CIK, when the schedule carries one. SCHEDULE 13G never does — its cover page has no CIK field — so this is populated on 13D filings only.",
"type": "string"
},
"citizenship": {
"description": "SEC citizenship or place-of-organization code — a US state (\"DE\"), or an SEC country code (\"X1\" United States, \"E9\" Cayman Islands).",
"type": "string"
},
"excludes_certain_shares": {
"description": "True when the reported aggregate deliberately excludes shares this person disclaims beneficial ownership of. Absent when the filing does not answer.",
"type": "boolean"
},
"name": {
"description": "Reporting person as named on the cover page.",
"type": "string"
},
"notes": {
"description": "The filer's own cover-page footnote, usually the share count the percentage was computed against. Clipped when long — the full text is in the filing.",
"type": "string"
},
"percent_of_class": {
"description": "Percent of the class this person beneficially owns (0-100), as this person reports it. Per person, not per filing: joint filers report overlapping shares, so these do not sum to a group total.",
"type": "number"
},
"person_types": {
"description": "SEC type-of-reporting-person codes — IN individual, CO corporation, PN partnership, IA investment adviser, HC holding company, OO other. One person can carry several.",
"items": {
"type": "string"
},
"type": "array"
},
"shared_dispositive_power": {
"description": "Shares this person may sell or transfer jointly with another party.",
"type": "number"
},
"shared_voting_power": {
"description": "Shares this person votes jointly with another party.",
"type": "number"
},
"sole_dispositive_power": {
"description": "Shares this person alone may sell or transfer.",
"type": "number"
},
"sole_voting_power": {
"description": "Shares this person alone may vote.",
"type": "number"
}
},
"required": [
"name",
"person_types"
],
"type": "object"
},
"type": "array"
},
"schedule": {
"description": "Which schedule this is — 13D activist, 13G passive.",
"enum": [
"13D",
"13G"
],
"type": "string"
},
"security_class": {
"description": "Title of the class of securities the schedule covers. A multi-class issuer has a separate schedule per class, so percentages are of this class only.",
"type": "string"
}
},
"required": [
"form",
"schedule",
"is_amendment",
"accession_number",
"filing_date",
"cusips",
"purpose_truncated",
"reporting_persons"
],
"type": "object"
},
"type": "array"
},
"filings_parsed": {
"description": "Filings actually fetched and parsed — total_structured_filings capped by limit.",
"type": "number"
},
"form_kind": {
"description": "The schedule filter applied — the requested value, or the default \"all\".",
"enum": [
"all",
"13D",
"13G"
],
"type": "string"
},
"issuer": {
"description": "The issuer input, echoed.",
"type": "string"
},
"issuer_cik": {
"description": "CIK of the resolved issuer, zero-padded to 10 digits.",
"type": "string"
},
"issuer_name": {
"description": "EDGAR-conformed name of the resolved issuer.",
"type": "string"
},
"legacy_filings_before_coverage": {
"description": "Legacy SC 13D / SC 13G filings in the issuer's recent submissions window — pre-2024-12-18 stakes this tool cannot parse. Reach them with secedgar_search_filings and read them with secedgar_get_filing. A floor, not a lifetime count: the submissions window holds the last year or 1,000 filings of every type, whichever is more.",
"type": "number"
},
"notice": {
"description": "Guidance when no filings matched — names the coverage boundary and the fallback.",
"type": "string"
},
"shown": {
"description": "Number of filings returned.",
"type": "number"
},
"structured_coverage_from": {
"description": "First filing date on which SEC required this XML format (YYYY-MM-DD). Blockholder filings before it exist but are not parseable into this schema.",
"type": "string"
},
"total_structured_filings": {
"description": "Structured SCHEDULE 13D/13G filings matching the form filter in the issuer's recent submissions window, before the limit. The population the returned filings are the newest slice of.",
"type": "number"
},
"truncated": {
"description": "True when filings were capped by limit.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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 to read the next page. Use section to jump directly to a heading (e.g. 'risk factors', 'item 7') without needing an offset.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"accession_number": {
"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.",
"pattern": "^(?:\\d{10}-\\d{2}-\\d{6}|\\d{18})$",
"type": "string"
},
"cik": {
"description": "Company CIK, digits only (resolve via secedgar_company_search if you have a ticker or name). Optional but recommended — speeds up archive lookup. If omitted, likely filing CIKs are inferred from SEC search metadata and archive paths.",
"pattern": "^\\d{1,10}$",
"type": "string"
},
"content_limit": {
"default": 50000,
"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.",
"maximum": 200000,
"minimum": 1000,
"type": "integer"
},
"document": {
"description": "Specific document filename within the filing (e.g., \"ex-21.htm\" for subsidiaries list). Default: the primary document. Available documents are listed in the response metadata under documents; entries marked binary hold no text and are rejected.",
"type": "string"
},
"include_xbrl": {
"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.",
"type": "boolean"
},
"offset": {
"default": 0,
"description": "Character offset into the extracted document text. Pass next_offset from a truncated response to continue reading the next page. Default 0 reads from the beginning.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"section": {
"description": "Jump to a named section by case-insensitive substring match against detected headings (e.g. 'risk factors', 'item 7', 'certain relationships'). Matching also ignores whitespace and quote-style differences, so a heading copied from the outline resolves whether it carries the filing's non-breaking spaces and curly quotes or plain ones. Takes precedence over offset when both are provided. On a miss, the error message includes the detected outline so you can pick the correct heading.",
"minLength": 1,
"type": "string"
}
},
"required": [
"accession_number"
],
"type": "object"
},
"name": "secedgar_get_filing",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"accession_number",
"cik",
"primary_document",
"documents",
"content",
"content_truncated",
"content_total_length",
"filing_url"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"accession_number": {
"description": "Filing accession number, normalized to dash format.",
"type": "string"
},
"cap": {
"description": "The `content_limit` that was applied.",
"type": "number"
},
"cik": {
"description": "Filing entity CIK, zero-padded to 10 digits.",
"type": "string"
},
"company_name": {
"description": "Filing entity name. Absent if the CIK did not resolve to a known entity.",
"type": "string"
},
"content": {
"description": "Document text content for this page window.",
"type": "string"
},
"content_total_length": {
"description": "Full document length before any truncation.",
"type": "number"
},
"content_truncated": {
"description": "True if content was truncated at content_limit.",
"type": "boolean"
},
"documents": {
"additionalProperties": false,
"description": "Filing documents grouped by category. Every name is a valid document input EXCEPT entries carrying binary: true — scanned pages, PDFs, packaged archives and spreadsheets, which hold no text and are rejected with a binary_document error. Scans can outnumber readable documents in a filing, so read the flag before picking a name. XBRL viewer artifacts are suppressed by default; setting include_xbrl=true surfaces them under the xbrl bucket.",
"properties": {
"auxiliary": {
"description": "Other supporting documents that aren't the primary, exhibits, or XBRL artifacts (cover pages, audit consent letters, embedded graphics).",
"items": {
"additionalProperties": false,
"description": "One document entry from the filing.",
"properties": {
"binary": {
"description": "Present and true when the entry holds binary bytes — a scanned page or logo, a PDF exhibit, a packaged archive or spreadsheet. These cannot be converted to text and are rejected by the document input. Absent for readable entries.",
"type": "boolean"
},
"description": {
"description": "Human-readable description (e.g., \"Annual Report\", \"Subsidiaries of the Registrant\"). Absent when SEC published none for this entry.",
"type": "string"
},
"name": {
"description": "Document filename within the filing archive.",
"type": "string"
},
"size": {
"description": "File size in bytes.",
"type": "number"
},
"type": {
"description": "SEC document type from the submission header (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\", \"XML\"). When the submission header is unavailable, falls back to a label inferred from the filename: known XBRL artifacts (\"XBRL-LINKBASE\", \"XBRL-INSTANCE\", etc.), \"exhibit\" for common exhibit filename patterns (ex-21.htm, exhibit21, dex991), \"GRAPHIC\"/\"PDF\"/\"BINARY\" for known binary file extensions, and \"unknown\" for everything else.",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"exhibits": {
"description": "Filed exhibits (EX-21 subsidiaries, EX-31/32 certifications, EX-99 press releases, etc.). Excludes XBRL technical exhibits (EX-101.*). Identified by the EX- prefix on the document type, or by common exhibit filename patterns when the submission header is unavailable (type \"exhibit\"). Exhibits with unrecognizable filenames may still appear under auxiliary in the header-less case.",
"items": {
"additionalProperties": false,
"description": "One document entry from the filing.",
"properties": {
"binary": {
"description": "Present and true when the entry holds binary bytes — a scanned page or logo, a PDF exhibit, a packaged archive or spreadsheet. These cannot be converted to text and are rejected by the document input. Absent for readable entries.",
"type": "boolean"
},
"description": {
"description": "Human-readable description (e.g., \"Annual Report\", \"Subsidiaries of the Registrant\"). Absent when SEC published none for this entry.",
"type": "string"
},
"name": {
"description": "Document filename within the filing archive.",
"type": "string"
},
"size": {
"description": "File size in bytes.",
"type": "number"
},
"type": {
"description": "SEC document type from the submission header (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\", \"XML\"). When the submission header is unavailable, falls back to a label inferred from the filename: known XBRL artifacts (\"XBRL-LINKBASE\", \"XBRL-INSTANCE\", etc.), \"exhibit\" for common exhibit filename patterns (ex-21.htm, exhibit21, dex991), \"GRAPHIC\"/\"PDF\"/\"BINARY\" for known binary file extensions, and \"unknown\" for everything else.",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"primary": {
"description": "Primary filing document(s). Typically a single entry whose type matches the form (e.g., \"10-K\").",
"items": {
"additionalProperties": false,
"description": "One document entry from the filing.",
"properties": {
"binary": {
"description": "Present and true when the entry holds binary bytes — a scanned page or logo, a PDF exhibit, a packaged archive or spreadsheet. These cannot be converted to text and are rejected by the document input. Absent for readable entries.",
"type": "boolean"
},
"description": {
"description": "Human-readable description (e.g., \"Annual Report\", \"Subsidiaries of the Registrant\"). Absent when SEC published none for this entry.",
"type": "string"
},
"name": {
"description": "Document filename within the filing archive.",
"type": "string"
},
"size": {
"description": "File size in bytes.",
"type": "number"
},
"type": {
"description": "SEC document type from the submission header (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\", \"XML\"). When the submission header is unavailable, falls back to a label inferred from the filename: known XBRL artifacts (\"XBRL-LINKBASE\", \"XBRL-INSTANCE\", etc.), \"exhibit\" for common exhibit filename patterns (ex-21.htm, exhibit21, dex991), \"GRAPHIC\"/\"PDF\"/\"BINARY\" for known binary file extensions, and \"unknown\" for everything else.",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
},
"xbrl": {
"description": "XBRL viewer artifacts and machine-readable taxonomy files. Only present when include_xbrl=true.",
"items": {
"additionalProperties": false,
"description": "One document entry from the filing.",
"properties": {
"binary": {
"description": "Present and true when the entry holds binary bytes — a scanned page or logo, a PDF exhibit, a packaged archive or spreadsheet. These cannot be converted to text and are rejected by the document input. Absent for readable entries.",
"type": "boolean"
},
"description": {
"description": "Human-readable description (e.g., \"Annual Report\", \"Subsidiaries of the Registrant\"). Absent when SEC published none for this entry.",
"type": "string"
},
"name": {
"description": "Document filename within the filing archive.",
"type": "string"
},
"size": {
"description": "File size in bytes.",
"type": "number"
},
"type": {
"description": "SEC document type from the submission header (e.g., \"10-K\", \"EX-21.1\", \"GRAPHIC\", \"XML\"). When the submission header is unavailable, falls back to a label inferred from the filename: known XBRL artifacts (\"XBRL-LINKBASE\", \"XBRL-INSTANCE\", etc.), \"exhibit\" for common exhibit filename patterns (ex-21.htm, exhibit21, dex991), \"GRAPHIC\"/\"PDF\"/\"BINARY\" for known binary file extensions, and \"unknown\" for everything else.",
"type": "string"
}
},
"required": [
"name",
"type"
],
"type": "object"
},
"type": "array"
}
},
"required": [
"primary",
"exhibits",
"auxiliary"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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 did not match any detected heading in 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. Other values are possible when a failure originates below the handler.",
"examples": [
"document_not_found",
"no_documents",
"binary_document",
"filing_not_found",
"offset_out_of_range",
"section_not_found",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"filing_date": {
"description": "Date the filing was submitted (YYYY-MM-DD). Absent under the same conditions as form.",
"type": "string"
},
"filing_url": {
"description": "Direct URL to the filing on SEC.gov.",
"type": "string"
},
"form": {
"description": "Form type (e.g., \"10-K\", \"10-Q\"). From the company's submissions feed for a recent filing, else from the filing's own SEC header. Absent only when neither source carries it.",
"type": "string"
},
"next_offset": {
"description": "Character offset to pass as offset on the next call to continue reading. Only present when the response was truncated. Calling agents should follow this until content_truncated is false.",
"type": "number"
},
"notice": {
"description": "Guidance on reading the next page when the content was capped.",
"type": "string"
},
"outline": {
"description": "Document outline — up to 50 detected headings with their character offsets. Present on the first page of a truncated response (offset=0, no section). Use a heading offset as offset, or pass heading text as section, to jump to that section.",
"items": {
"additionalProperties": false,
"description": "One detected heading with its offset.",
"properties": {
"heading": {
"description": "Detected heading text.",
"type": "string"
},
"offset": {
"description": "Character offset of this heading in the full document. Pass as offset to jump directly to this section.",
"type": "number"
}
},
"required": [
"heading",
"offset"
],
"type": "object"
},
"type": "array"
},
"period_ending": {
"description": "Period the filing reports on (YYYY-MM-DD), from the same source as form. Absent for forms with no period of report (S-8, Form 4, proxy statements) and when neither source carries it.",
"type": "string"
},
"primary_document": {
"description": "Filename of the filing's actual primary document (e.g., the 10-K HTML file).",
"type": "string"
},
"requested_document": {
"description": "Filename of the specific document requested via the document param. Only present when document differs from primary_document.",
"type": "string"
},
"shown": {
"description": "Characters of document text returned on this page.",
"type": "number"
},
"truncated": {
"description": "True when the document is longer than `content_limit` allowed through.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"company": {
"description": "Ticker symbol (e.g., \"AAPL\") or CIK number. Ticker is preferred.",
"minLength": 1,
"type": "string"
},
"concept": {
"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.",
"minLength": 1,
"type": "string"
},
"limit": {
"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.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"period_type": {
"description": "Filter to annual (FY) or quarterly (Q1-Q4) data. \"all\" returns both. When omitted, defaults to \"annual\"; instant (balance-sheet) concepts automatically fall back to returning the full series on the first call when the annual filter yields nothing (#48).",
"enum": [
"annual",
"quarterly",
"all"
],
"type": "string"
},
"taxonomy": {
"default": "us-gaap",
"description": "XBRL taxonomy. us-gaap for US companies, ifrs-full for foreign filers, dei for entity info (shares outstanding).",
"enum": [
"us-gaap",
"ifrs-full",
"dei"
],
"type": "string"
}
},
"required": [
"company",
"concept"
],
"type": "object"
},
"name": "secedgar_get_financials",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"company",
"cik",
"concept",
"label",
"unit",
"data"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"caveats": {
"description": "Data-completeness warnings about the returned series. Two kinds. On quarterly results, one entry when one or two calendar quarters are absent from every recent qualifying year — SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact, so the calendar quarter fiscal Q4 spans has no frame-tagged value, and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way. Applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones. On any result, one entry when the series stops well short of today — either because the concept resolved to an XBRL tag SEC has retired from the taxonomy (the current tags reported nothing), or because a current tag's series ends more than two years plus a filing window back, which is what a filer migrating to a different element or dropping the disclosure looks like. Absent when the series has nothing to flag.",
"items": {
"type": "string"
},
"type": "array"
},
"cik": {
"description": "Resolved CIK, zero-padded to 10 digits.",
"type": "string"
},
"company": {
"description": "Resolved entity name (SEC-conformed).",
"type": "string"
},
"concept": {
"description": "XBRL tag behind the newest value. A friendly name can walk several tags, so each row names its own.",
"type": "string"
},
"data": {
"description": "Deduplicated time series, newest first — one value per calendar period. Where SEC's period frame sits on a proxy statement's figure (the pay-versus-performance table re-tags net income), the value comes from the filer's own report of the same period; an annual period SEC framed on a 10-Q's trailing-twelve-month figure is left out, since the filer has not closed that year.",
"items": {
"additionalProperties": false,
"description": "One reported value with its period, fiscal context, source filing, and source tag.",
"properties": {
"accession_number": {
"description": "Source filing accession number for secedgar_get_filing.",
"type": "string"
},
"end": {
"description": "Period end date (YYYY-MM-DD).",
"type": "string"
},
"filed": {
"description": "Date the source filing was submitted (YYYY-MM-DD).",
"type": "string"
},
"fiscal_period": {
"description": "Fiscal period of the source filing (FY, Q1, Q2, Q3, Q4), not the data period. Null when the source filing did not encode a fiscal period.",
"type": [
"string",
"null"
]
},
"fiscal_year": {
"description": "Fiscal year of the source filing, not the data period — every comparative period restated in the same filing carries that filing's fiscal year, so use end (or period) as the time key. Null when the source filing did not encode a fiscal year.",
"type": [
"number",
"null"
]
},
"form": {
"description": "Source filing type (10-K, 10-Q, etc.).",
"type": "string"
},
"period": {
"description": "Calendar period label (e.g., \"CY2023\", \"CY2023Q3\").",
"type": "string"
},
"start": {
"description": "Period start date (YYYY-MM-DD). Duration items only.",
"type": "string"
},
"tag": {
"description": "XBRL tag this value was reported under — differs from concept when an older or successor tag in the friendly name answers this period.",
"type": "string"
},
"value": {
"description": "Reported value.",
"type": "number"
}
},
"required": [
"period",
"value",
"end",
"fiscal_year",
"fiscal_period",
"form",
"filed",
"accession_number",
"tag"
],
"type": "object"
},
"type": "array"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe handle holding the same time series. Use for cross-company JOINs via secedgar_dataframe_query. The source-filing fiscal keys are materialized as source_filing_fy/source_filing_fp — order, group, and window by period_end, not by those columns. Absent when canvas is unavailable.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
}
},
"required": [
"name",
"row_count",
"expires_at"
],
"type": "object"
},
"description": {
"description": "XBRL taxonomy description of the concept tag. Often absent for company-extension tags or older concepts.",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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. `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. Other values are possible when a failure originates below the handler.",
"examples": [
"company_not_found",
"ambiguous_company",
"unknown_concept",
"no_concept_data",
"no_frame_data",
"no_period_data",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"label": {
"description": "Human-readable taxonomy label of the concept tag.",
"type": "string"
},
"notice": {
"description": "Guidance when the inline series was capped, or when the full series is staged as a dataframe.",
"type": "string"
},
"shown": {
"description": "Number of periods shown inline.",
"type": "number"
},
"tags_tried": {
"description": "XBRL tags that were attempted (shown when using friendly names that map to multiple tags).",
"items": {
"type": "string"
},
"type": "array"
},
"truncated": {
"description": "True when the inline data[] was capped by limit.",
"type": "boolean"
},
"unit": {
"description": "Unit of measure of the newest value (e.g., \"USD\", \"shares\", \"USD/shares\").",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"fund": {
"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.",
"minLength": 1,
"type": "string"
},
"limit": {
"default": 20,
"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.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 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.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"report_date": {
"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.",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
},
"series_id": {
"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.",
"pattern": "^S\\d{9}$",
"type": "string"
}
},
"required": [
"fund"
],
"type": "object"
},
"name": "secedgar_get_fund_holdings",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"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"
]
}
],
"properties": {
"accession_number": {
"description": "Accession number — pass to secedgar_get_filing for the full document.",
"type": "string"
},
"as_of": {
"description": "The portfolio date these holdings are reported as of, and the publication lag behind it.",
"type": "string"
},
"available_report_periods": {
"description": "Period end dates of this fund's reports, newest first — the horizon report_date can address, not the fund's full history. It reaches back roughly a decade of quarterly reports, and a period older than that is refused rather than served. A period inside the horizon can still be missing from the list: the dates come from the registrant's recent submissions window, which a trust filing thousands of reports a year outruns in months, and a report the window no longer reaches is dated by reading it only when report_date asks for it.",
"items": {
"type": "string"
},
"type": "array"
},
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"class_ids": {
"description": "SEC class IDs of the share classes covered. One report covers every class of the series, so a fund with both an ETF and an admiral-share class reports them together.",
"items": {
"type": "string"
},
"type": "array"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding every position in the report (the inline holdings[] is a preview capped at limit). Each row carries the fund keys — series_id, registrant_cik, report_period_date, accession_number — alongside the position fields, so it joins against the 13F and insider dataframes on cusip. Absent when canvas is unavailable or the report had no positions.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
}
},
"required": [
"name",
"row_count",
"expires_at"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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. Other values are possible when a failure originates below the handler.",
"examples": [
"fund_not_found",
"ambiguous_fund",
"series_required",
"no_filings_found",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"filing_date": {
"description": "Date the report was submitted to EDGAR (YYYY-MM-DD).",
"type": "string"
},
"form": {
"description": "EDGAR form name — \"NPORT-P\", or \"NPORT-P/A\" for an amended report.",
"type": "string"
},
"fund": {
"description": "The fund input, echoed.",
"type": "string"
},
"holdings": {
"description": "One page of positions, `limit` rows starting at `offset`, largest first by percent of net assets.",
"items": {
"additionalProperties": false,
"description": "One position from the fund portfolio.",
"properties": {
"asset_category": {
"description": "SEC asset-type code — EC equity-common, EP equity-preferred, DBT debt, RA repurchase agreement, STIV short-term investment vehicle, DE derivative. A filer that classifies a position as Other reports its own label here instead of a code (\"Right\"), because the code in that case is just \"OTHER\".",
"type": "string"
},
"balance": {
"description": "Units held, counted in whatever `units` names — shares, principal, or contracts.",
"type": "number"
},
"country": {
"description": "ISO 3166 country of investment.",
"type": "string"
},
"currency": {
"description": "ISO 4217 currency the position is denominated in.",
"type": "string"
},
"cusip": {
"description": "9-character CUSIP. Absent when the filer omits it.",
"type": "string"
},
"isin": {
"description": "ISIN. Absent when the filer reports another identifier.",
"type": "string"
},
"issuer_category": {
"description": "SEC issuer-type code — CORP corporate, MUN municipal, USGSE US government-sponsored, RF registered fund. A filer that classifies an issuer as Other reports its own label here instead of a code (\"Future\", \"Warrant\").",
"type": "string"
},
"lei": {
"description": "Legal Entity Identifier of the issuer, when reported.",
"type": "string"
},
"name": {
"description": "Issuer name as the fund reports it. A derivative position routinely reports the literal \"N/A\" here and names the instrument in title instead, so group and label positions by title when asset_category marks a derivative.",
"type": "string"
},
"payoff_profile": {
"description": "\"Long\", \"Short\", or \"N/A\" for instruments with no direction.",
"type": "string"
},
"percent_of_net_assets": {
"description": "Percent of the fund's net assets, as the filer computes it. Negative on a short position — a leveraged fund's swap or futures leg regularly reports several percent below zero — so this is not bounded at 0.",
"type": "number"
},
"title": {
"description": "The filer's own title for the security, often an abbreviated trading name.",
"type": "string"
},
"units": {
"description": "What balance counts — NS number of shares, PA principal amount, NC number of contracts, OU other.",
"type": "string"
},
"value_usd": {
"description": "Market value of the position in USD at the report date.",
"type": "number"
}
},
"required": [
"name"
],
"type": "object"
},
"type": "array"
},
"is_final_filing": {
"description": "True when the fund reports this as its last filing on the series, which marks a liquidation or merger. Absent when the filing does not answer.",
"type": "boolean"
},
"net_assets_usd": {
"description": "Fund net assets in USD at the report date — the denominator of percent_of_net_assets.",
"type": "number"
},
"next_offset": {
"description": "Offset to pass on the next call to continue through the portfolio. Absent on the last page.",
"type": "number"
},
"notice": {
"description": "Guidance when the report carried no positions or the page fell past the end.",
"type": "string"
},
"offset": {
"description": "Position the returned page starts at, 0-based.",
"type": "number"
},
"publication_lag_days": {
"description": "Days between the portfolio date and the filing date. Absent when the report omits its period date.",
"type": "number"
},
"registrant_cik": {
"description": "CIK of the registrant trust, zero-padded to 10 digits.",
"type": "string"
},
"registrant_name": {
"description": "EDGAR-conformed name of the registrant trust.",
"type": "string"
},
"report_period_date": {
"description": "Last day of the period this portfolio is reported as of (YYYY-MM-DD). Holdings are the fund's positions on this date, not today's. Absent only when the filer omits it.",
"type": "string"
},
"report_period_end": {
"description": "Last day of the fiscal year the reporting period falls in (YYYY-MM-DD) — the fund's fiscal year end, not the portfolio date.",
"type": "string"
},
"series_id": {
"description": "SEC series ID of the fund this report covers. Absent when the registrant files as a single fund with no series structure, which is how some older exchange-traded trusts are organized.",
"type": "string"
},
"series_name": {
"description": "Fund name as the filer states it on the report. A closed-end fund organized as a single registrant names itself here with no series_id alongside; absent only when the filer leaves the field blank or writes \"N/A\".",
"type": "string"
},
"shown": {
"description": "Number of positions shown inline.",
"type": "number"
},
"total_assets_usd": {
"description": "Fund total assets in USD at the report date.",
"type": "number"
},
"total_holdings": {
"description": "Positions in the report, before offset and limit — the size of the full portfolio.",
"type": "number"
},
"total_liabilities_usd": {
"description": "Fund total liabilities in USD at the report date.",
"type": "number"
},
"truncated": {
"description": "True when the inline holdings list was capped by limit.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"company": {
"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 resolves to the top-ranked one — exact name first, then prefix, then substring — so pass a ticker or CIK when the issuer must be exact.",
"minLength": 1,
"type": "string"
},
"filed_after": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"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": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"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."
},
"limit": {
"default": 20,
"description": "Maximum number of transactions to return across all Form 4 filings fetched. Filings are scanned newest-first. Default 20.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"transaction_type": {
"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.",
"enum": [
"purchase",
"sale",
"all"
],
"type": "string"
}
},
"required": [
"company"
],
"type": "object"
},
"name": "secedgar_get_insider_transactions",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"issuer_name",
"issuer_cik",
"transactions",
"filings_scanned"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding the full parsed transaction set from the scanned filings (the inline transactions[] is a preview capped at limit). Each row carries the issuer (issuer_cik, issuer_ticker) plus the transaction fields, so it aggregates net buy/sell by insider and joins across issuers. Query with secedgar_dataframe_query. Absent when canvas is unavailable or no transactions were parsed.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
},
"truncated": {
"description": "True when Form 4 filings exist beyond those parsed — past the newest-filings sample, or, with a date window, inside the window beyond the 100-filing cap or past the 10 archive pages read. Narrow the window to reach the rest.",
"type": "boolean"
}
},
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `company_not_found`: The company input does not resolve to a known company. `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. Other values are possible when a failure originates below the handler.",
"examples": [
"company_not_found",
"no_filings_found",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"filings_scanned": {
"description": "Number of Form 4 filings scanned to produce the result.",
"type": "number"
},
"history_scanned_through": {
"description": "Filing date of the oldest Form 4 parsed (YYYY-MM-DD). Present only when a date window was given; absent when the window held no Form 4 filing.",
"type": "string"
},
"issuer_cik": {
"description": "Issuer CIK, zero-padded to 10 digits.",
"type": "string"
},
"issuer_name": {
"description": "Issuer entity name (SEC-conformed).",
"type": "string"
},
"issuer_ticker": {
"description": "Issuer ticker symbol when available.",
"type": "string"
},
"notice": {
"description": "Guidance when results are empty after filtering — explains the filter applied and suggests alternatives.",
"type": "string"
},
"shown": {
"description": "Number of transactions shown inline.",
"type": "number"
},
"transactions": {
"description": "Insider transactions, newest filing first. Preview capped at `limit` — the full scanned set lives on the canvas dataframe (see `dataset`).",
"items": {
"additionalProperties": false,
"description": "One insider transaction parsed from a Form 4 filing.",
"properties": {
"accession_number": {
"description": "Form 4 accession number — pass to secedgar_get_filing for the raw XML.",
"type": "string"
},
"direction": {
"description": "Whether shares were acquired or disposed. \"acquire\" = buy, award, exercise; \"dispose\" = sale, gift, return. Absent when shares_traded is absent.",
"enum": [
"acquire",
"dispose"
],
"type": "string"
},
"filing_date": {
"description": "Date the Form 4 was filed (YYYY-MM-DD).",
"type": "string"
},
"is_derivative": {
"description": "True for derivative security transactions (options, RSUs, convertible notes). False for direct equity transactions.",
"type": "boolean"
},
"ownership_nature": {
"description": "Nature of indirect ownership (e.g., \"By Trust\", \"By Spouse\"). Only present when ownership_type is indirect.",
"type": "string"
},
"ownership_type": {
"description": "D = direct ownership, I = indirect (through a trust, family member, etc.). Absent when not reported.",
"enum": [
"direct",
"indirect"
],
"type": "string"
},
"period_of_report": {
"description": "Transaction date per the filing period (YYYY-MM-DD).",
"type": "string"
},
"price_per_share": {
"description": "Price per share in USD. 0 for gifts and RSU awards (no cash consideration). Absent when not reported.",
"type": "number"
},
"relationship": {
"description": "Relationship to issuer (e.g., \"Director\", \"Officer (CEO)\", \"10% Owner\").",
"type": "string"
},
"reporting_person": {
"description": "Name of the insider who filed the Form 4.",
"type": "string"
},
"security_title": {
"description": "Security type (e.g., \"Common Stock\").",
"type": "string"
},
"shares_owned_after": {
"description": "Total shares owned after this transaction, as reported. Absent when omitted by the filer.",
"type": "number"
},
"shares_traded": {
"description": "Absolute number of shares involved (always positive). Absent when the filing omits this field. Use `direction` to distinguish acquisitions from disposals.",
"type": "number"
},
"transaction_code": {
"description": "Single-letter SEC transaction code: P = purchase, S = sale, M = exercise, A = award, G = gift, F = tax withholding, C = conversion, others exist.",
"type": "string"
},
"transaction_date": {
"description": "Date the transaction occurred (YYYY-MM-DD). Absent on some filings.",
"type": "string"
},
"transaction_type": {
"description": "Human-readable description of the transaction code (e.g., \"purchase\", \"sale\", \"conversion_of_derivative\").",
"type": "string"
}
},
"required": [
"filing_date",
"accession_number",
"reporting_person",
"relationship",
"security_title",
"transaction_code",
"transaction_type",
"is_derivative"
],
"type": "object"
},
"type": "array"
},
"truncated": {
"description": "True when the inline transactions[] was capped by limit.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "Fetch 13F-HR quarterly institutional holdings by parsing the SEC EDGAR information table XML. company is the institutional filer — its 10-digit CIK (e.g. 0000102909), a ticker, or an entity name (names outside EDGAR's ticker file resolve through EDGAR entity search) — and the tool returns what that institution holds. A name that matches several EDGAR filers (some legal names are shared across entities) returns those candidates so you can retry with the exact CIK, rather than guessing. For the reverse direction — which institutions hold a given portfolio company — use secedgar_find_holders, whose filer_cik results feed straight back into this tool. The 13F information table lists each position: issuer name, CUSIP, shares held, market value (in whole USD), and put/call designation for options. Sub-lines for the same security are consolidated into distinct positions sorted by value by default (set consolidate=false for raw filing rows). The inline holdings list is one page of limit rows starting at offset — pass the returned next_offset to walk further down a large information table. The full parsed holdings set is also materialized as df_<id> when a canvas is available — inspect it with secedgar_dataframe_describe, then query it with secedgar_dataframe_query to aggregate the whole filing or self-join across quarters on cusip + reporting_period. Institutions with less than $100M in 13(f) securities are exempt and may not file. Use secedgar_search_filings with forms=[\"13F-HR\"] for broader search.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"company": {
"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.",
"minLength": 1,
"type": "string"
},
"consolidate": {
"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.",
"type": "boolean"
},
"limit": {
"default": 20,
"description": "Maximum number of holdings rows to return. 13F filings from large institutions can contain thousands of positions. Default 20.",
"maximum": 500,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 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.",
"maximum": 9007199254740991,
"minimum": 0,
"type": "integer"
},
"quarter": {
"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.",
"type": "string"
}
},
"required": [
"company"
],
"type": "object"
},
"name": "secedgar_get_institutional_holdings",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"filer_name",
"filer_cik",
"filing_date",
"accession_number",
"total_holdings_in_filing",
"offset",
"holdings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"accession_number": {
"description": "Accession number for this 13F-HR filing — pass to secedgar_get_filing for the full document.",
"type": "string"
},
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding every parsed position from this 13F filing (the inline holdings[] is a preview capped at limit). Each row carries the filer metadata (filer_cik, filer_name, reporting_period, filing_date, accession_number) plus the position fields, so it self-joins across quarters/filers on cusip + reporting_period. Reflects the consolidate setting (consolidated positions when true, raw info-table sub-lines with investment_discretion when false). Query with secedgar_dataframe_query. Absent when canvas is unavailable or the filing had no holdings.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
}
},
"required": [
"name",
"row_count",
"expires_at"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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. Other values are possible when a failure originates below the handler.",
"examples": [
"company_not_found",
"ambiguous_entity",
"no_filings_found",
"no_info_table",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"filer_cik": {
"description": "CIK of the 13F filer, zero-padded to 10 digits.",
"type": "string"
},
"filer_name": {
"description": "Name of the institutional filer (the 13F submitter).",
"type": "string"
},
"filing_date": {
"description": "Date the 13F was submitted (YYYY-MM-DD).",
"type": "string"
},
"holdings": {
"description": "One page of holdings, `limit` rows starting at `offset` — consolidated positions sorted by market value when consolidate=true, else raw information-table rows in filing order.",
"items": {
"additionalProperties": false,
"description": "One row from the 13F information table.",
"properties": {
"cusip": {
"description": "9-digit CUSIP identifier. Absent when omitted by the filer.",
"type": "string"
},
"investment_discretion": {
"description": "SOLE = sole investment discretion, DFND = defined (shared/advised), OTR = other. Absent when not reported.",
"enum": [
"SOLE",
"DFND",
"OTR"
],
"type": "string"
},
"issuer_name": {
"description": "Name of the issuer whose securities are held.",
"type": "string"
},
"market_value_usd": {
"description": "Market value of the position in whole USD at the reporting date. SEC Form 13F has reported whole dollars since the 2023 amendments; values from filings before 2023-01-03 (originally thousands) are normalized to whole USD. Absent when not reported.",
"type": "number"
},
"put_call": {
"description": "Options designation. Present only when the row represents a put or call option position.",
"enum": [
"Put",
"Call"
],
"type": "string"
},
"shares_or_principal_amount": {
"description": "Number of shares (for equities) or principal amount (for debt securities). Absent when not reported.",
"type": "number"
},
"shares_or_principal_type": {
"description": "SH = share position, PRN = principal amount (bonds, notes). Absent when not reported.",
"enum": [
"SH",
"PRN"
],
"type": "string"
},
"title_of_class": {
"description": "Security class (e.g., \"COM\", \"CL A\", \"ETF\"). Absent when not reported.",
"type": "string"
}
},
"required": [
"issuer_name"
],
"type": "object"
},
"type": "array"
},
"next_offset": {
"description": "Offset to pass on the next call to continue through the positions. Absent on the last page (no rows remain past this one).",
"type": "number"
},
"notice": {
"description": "Guidance when no filings were found or the result set is empty — suggests alternatives.",
"type": "string"
},
"offset": {
"description": "Row the returned page starts at, 0-based — the effective offset applied.",
"type": "number"
},
"reporting_period": {
"description": "The calendar-quarter end date this 13F covers (YYYY-MM-DD), from the filing cover page. Absent if not surfaced in the filing.",
"type": "string"
},
"shown": {
"description": "Number of holdings shown inline.",
"type": "number"
},
"total_holdings_in_filing": {
"description": "Total number of raw information-table rows in this filing, before consolidation and the limit.",
"type": "number"
},
"total_positions": {
"description": "Number of distinct positions after consolidating info-table sub-lines, before the limit. Present only when consolidate=true.",
"type": "number"
},
"truncated": {
"description": "True when the inline holdings[] was capped by limit.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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. 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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"company": {
"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.",
"minLength": 1,
"type": "string"
},
"filed_after": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"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": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"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."
},
"items": {
"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.",
"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,
"type": "array"
},
"limit": {
"default": 20,
"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.",
"maximum": 100,
"minimum": 1,
"type": "integer"
}
},
"required": [
"company"
],
"type": "object"
},
"name": "secedgar_get_material_events",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"cik",
"company_name",
"total_matched",
"total_8k_scanned",
"item_distribution",
"filings"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"cik": {
"description": "Central Index Key of the resolved company, zero-padded to 10 digits.",
"type": "string"
},
"company_name": {
"description": "SEC-conformed company name.",
"type": "string"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding every scanned 8-K that passes the filter. Item codes ride as a comma-separated `item_codes` column, so item-frequency-over-time queries split it (`unnest(string_split(item_codes, ','))`). Absent when the result fits inline, canvas is unavailable, or materialization failed.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
},
"truncated": {
"description": "True when archive pages in range went unread — the 10-page cap ended the scan, or an undated call stopped once limit was filled, which is before any archive page when the recent window alone fills it — so older matching filings may exist beyond the dataframe. Pass filed_after / filed_before to reach them.",
"type": "boolean"
}
},
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"type": "object"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `no_match`: No company matches the query. `multiple_matches`: The query is ambiguous and matches several companies. `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. Other values are possible when a failure originates below the handler.",
"examples": [
"no_match",
"multiple_matches",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"filings": {
"description": "Matching filings, newest first, capped at limit.",
"items": {
"additionalProperties": false,
"description": "One 8-K filing.",
"properties": {
"accession_number": {
"description": "Filing accession number, dash format. Pass to secedgar_get_filing for the document text.",
"type": "string"
},
"description": {
"description": "SEC-provided filing description. Absent when SEC published none.",
"type": "string"
},
"filing_date": {
"description": "Date the filing was submitted (YYYY-MM-DD).",
"type": "string"
},
"form": {
"description": "Form type — \"8-K\", or \"8-K/A\" for an amendment.",
"type": "string"
},
"items": {
"description": "Items this filing reports, decoded. Empty when EDGAR records no items for the filing, which happens on some older filings.",
"items": {
"additionalProperties": false,
"description": "One reported 8-K item.",
"properties": {
"code": {
"description": "Item code exactly as EDGAR reported it.",
"type": "string"
},
"label": {
"description": "Item title from Form 8-K. Absent for a code neither numbering regime defines, so the raw code is never given a guessed meaning.",
"type": "string"
},
"regime": {
"description": "Which numbering the code belongs to: \"current\" for the dotted scheme in force since 2004-08-23, \"legacy\" for the single-integer scheme before it. Absent for an unrecognized code shape.",
"enum": [
"current",
"legacy"
],
"type": "string"
}
},
"required": [
"code"
],
"type": "object"
},
"type": "array"
},
"primary_document": {
"description": "Primary document filename — pass as `document` to secedgar_get_filing. Press releases are usually separate EX-99 exhibits, listed in that tool's document catalog. Absent on older filings, which EDGAR records without one; secedgar_get_filing still resolves them from the accession number alone.",
"type": "string"
},
"report_date": {
"description": "Date of the reported event (YYYY-MM-DD), which usually precedes the filing date. Absent when SEC records none.",
"type": "string"
}
},
"required": [
"accession_number",
"form",
"filing_date",
"items"
],
"type": "object"
},
"type": "array"
},
"history_scanned_through": {
"description": "Oldest filing date reached by the scan (YYYY-MM-DD). Older filings were not examined: the recent window holds the last year or 1,000 filings of every form, whichever is more, and archive pages are read only for a date filter (every page overlapping it, up to 10) or to fill limit (stopping on the page that fills it). Absent when no filings were scanned.",
"type": "string"
},
"item_distribution": {
"additionalProperties": {
"type": "number"
},
"description": "Count of the 8-K filings scanned in the date window carrying each item code, before the items filter. Empty when no 8-K filings were scanned.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"items_filter": {
"description": "The item codes filtered on, echoed. Absent when no filter was applied.",
"items": {
"type": "string"
},
"type": "array"
},
"notice": {
"description": "Guidance when nothing matched — distinguishes an empty date window from an items filter that excluded everything.",
"type": "string"
},
"shown": {
"description": "Number of filings shown inline.",
"type": "number"
},
"total_8k_scanned": {
"description": "8-K filings inside the date window before the items filter — compare against total_matched to see how much the items filter removed.",
"type": "number"
},
"total_matched": {
"description": "Filings matching every applied filter across the whole scan, which may exceed limit and the inline list.",
"type": "number"
},
"truncated": {
"description": "True when the inline filings list was capped.",
"type": "boolean"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"company": {
"description": "Ticker symbol (e.g. \"AAPL\") or CIK number. Ticker is preferred.",
"minLength": 1,
"type": "string"
},
"period_type": {
"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.",
"enum": [
"annual",
"quarterly",
"both"
],
"type": "string"
},
"taxonomy": {
"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.",
"enum": [
"us-gaap",
"ifrs-full"
],
"type": "string"
}
},
"required": [
"company"
],
"type": "object"
},
"name": "secedgar_get_snapshot",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"company",
"cik",
"taxonomy",
"period_type",
"concepts_resolved",
"concepts_total",
"lines",
"gaps",
"caveats"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"caveats": {
"description": "Data-completeness warnings. One entry when one or two calendar quarters are absent from every recent qualifying year, because SEC reports a filer's fiscal Q4 as the 10-K residual rather than a discrete quarterly fact — this applies to calendar-year filers (no discrete Q4) as much as to off-calendar ones, and a filer whose other fiscal quarters span non-calendar durations loses a second quarter the same way. One further entry, prefixed with the concept name, per line whose values stop at least two full years behind the newest period this filer reports anywhere in the profile — either because the line resolved to an XBRL tag SEC has retired from the taxonomy, or because a current tag's series simply ends, which is what a migration to a different element or a dropped disclosure looks like. Empty when nothing needs flagging.",
"items": {
"type": "string"
},
"type": "array"
},
"cik": {
"description": "Resolved CIK, zero-padded to 10 digits.",
"type": "string"
},
"company": {
"description": "Resolved entity name (SEC-conformed).",
"type": "string"
},
"concepts_resolved": {
"description": "Concepts that produced at least one value.",
"type": "number"
},
"concepts_total": {
"description": "Concepts in the supported catalog that were attempted.",
"type": "number"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"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. Other values are possible when a failure originates below the handler.",
"examples": [
"company_not_found",
"ambiguous_company",
"no_company_facts",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"gaps": {
"description": "Concepts with no value for this filer. Deliberately explicit — a missing concept is never zero-filled or interpolated.",
"items": {
"additionalProperties": false,
"description": "One concept the filer does not report, with the tags that were tried.",
"properties": {
"concept": {
"description": "Friendly concept name that produced no value.",
"type": "string"
},
"group": {
"description": "Statement group the concept belongs to.",
"type": "string"
},
"label": {
"description": "Human-readable concept label.",
"type": "string"
},
"tags_tried": {
"description": "XBRL tags attempted, in priority order, before giving up.",
"items": {
"type": "string"
},
"type": "array"
}
},
"required": [
"concept",
"label",
"group",
"tags_tried"
],
"type": "object"
},
"type": "array"
},
"lines": {
"description": "Resolved concepts, ordered by statement group then concept name.",
"items": {
"additionalProperties": false,
"description": "One resolved concept with its latest value per period kind.",
"properties": {
"annual": {
"additionalProperties": false,
"description": "Latest full-year (CY####) value. Absent for point-in-time concepts and when period_type excludes it.",
"properties": {
"accession_number": {
"description": "Source filing accession number — pass to secedgar_get_filing.",
"type": "string"
},
"form": {
"description": "Source filing type (10-K, 10-Q, 20-F).",
"type": "string"
},
"period": {
"description": "Calendar period label (e.g. \"CY2024\", \"CY2025Q2\", \"CY2025Q2I\").",
"type": "string"
},
"period_end": {
"description": "Period end date (YYYY-MM-DD).",
"type": "string"
},
"tag": {
"description": "XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period.",
"type": "string"
},
"value": {
"description": "Reported value, in the line's unit.",
"type": "number"
}
},
"required": [
"period",
"value",
"period_end",
"form",
"accession_number",
"tag"
],
"type": "object"
},
"concept": {
"description": "Friendly concept name (e.g. \"revenue\").",
"type": "string"
},
"group": {
"description": "Statement group: income_statement, balance_sheet, cash_flow, per_share, or entity_info.",
"type": "string"
},
"instant": {
"additionalProperties": false,
"description": "Latest point-in-time (CY####Q#I) value. Present for balance-sheet and entity-info concepts.",
"properties": {
"accession_number": {
"description": "Source filing accession number — pass to secedgar_get_filing.",
"type": "string"
},
"form": {
"description": "Source filing type (10-K, 10-Q, 20-F).",
"type": "string"
},
"period": {
"description": "Calendar period label (e.g. \"CY2024\", \"CY2025Q2\", \"CY2025Q2I\").",
"type": "string"
},
"period_end": {
"description": "Period end date (YYYY-MM-DD).",
"type": "string"
},
"tag": {
"description": "XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period.",
"type": "string"
},
"value": {
"description": "Reported value, in the line's unit.",
"type": "number"
}
},
"required": [
"period",
"value",
"period_end",
"form",
"accession_number",
"tag"
],
"type": "object"
},
"label": {
"description": "Human-readable concept label.",
"type": "string"
},
"quarterly": {
"additionalProperties": false,
"description": "Latest single-quarter (CY####Q#) value. Absent for point-in-time concepts and when period_type excludes it.",
"properties": {
"accession_number": {
"description": "Source filing accession number — pass to secedgar_get_filing.",
"type": "string"
},
"form": {
"description": "Source filing type (10-K, 10-Q, 20-F).",
"type": "string"
},
"period": {
"description": "Calendar period label (e.g. \"CY2024\", \"CY2025Q2\", \"CY2025Q2I\").",
"type": "string"
},
"period_end": {
"description": "Period end date (YYYY-MM-DD).",
"type": "string"
},
"tag": {
"description": "XBRL tag this value was reported under — differs from the line's tag when an older or successor tag in the concept answers this period.",
"type": "string"
},
"value": {
"description": "Reported value, in the line's unit.",
"type": "number"
}
},
"required": [
"period",
"value",
"period_end",
"form",
"accession_number",
"tag"
],
"type": "object"
},
"tag": {
"description": "XBRL tag behind the newest value — each point names its own when the concept walks several.",
"type": "string"
},
"taxonomy": {
"description": "Taxonomy the value was read from.",
"type": "string"
},
"unit": {
"description": "Unit of measure of the newest value (e.g. \"USD\", \"USD/shares\", \"shares\").",
"type": "string"
}
},
"required": [
"concept",
"label",
"group",
"taxonomy",
"tag",
"unit"
],
"type": "object"
},
"type": "array"
},
"period_type": {
"description": "Duration periods reported, echoed from input.",
"type": "string"
},
"taxonomy": {
"description": "Taxonomy the concepts were resolved under, echoed from input.",
"type": "string"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"group": {
"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.",
"enum": [
"income_statement",
"balance_sheet",
"cash_flow",
"per_share",
"entity_info"
],
"type": "string"
},
"search": {
"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.",
"type": "string"
},
"taxonomy": {
"description": "Filter to a single XBRL taxonomy. us-gaap for US filers, ifrs-full for foreign filers, dei for entity info.",
"enum": [
"us-gaap",
"ifrs-full",
"dei"
],
"type": "string"
}
},
"type": "object"
},
"name": "secedgar_search_concepts",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"total",
"concepts"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"concepts": {
"description": "Matching concepts, ordered by group then alphabetical by name.",
"items": {
"additionalProperties": false,
"description": "One XBRL concept mapping with its friendly name, tags, and grouping.",
"properties": {
"group": {
"description": "Statement section this concept belongs to: income_statement, balance_sheet, cash_flow, per_share, or entity_info.",
"enum": [
"income_statement",
"balance_sheet",
"cash_flow",
"per_share",
"entity_info"
],
"type": "string"
},
"ifrs_tags": {
"description": "XBRL tags this friendly name resolves to under taxonomy \"ifrs-full\", tried in order — a different element set from tags, not a synonym list. Each one is confirmed present in a live 20-F filing. Absent when the concept has no IFRS equivalent, in which case taxonomy \"ifrs-full\" does not resolve it.",
"items": {
"type": "string"
},
"type": "array"
},
"label": {
"description": "Human-readable concept label.",
"type": "string"
},
"name": {
"description": "Friendly name to pass as `concept` to secedgar_get_financials or secedgar_fetch_frames, or in `concepts` to secedgar_compare_companies.",
"type": "string"
},
"related_tags": {
"description": "Alternate-DEFINITION tags (different meaning from `tags`, not historical synonyms) that a meaningful share of filers report this metric under instead — surfaced by secedgar_fetch_frames as `related_tags`. Present only when the concept has a known high-coverage alternate (e.g. cash → restricted-cash-inclusive total, equity → NCI-inclusive total). Query these separately; do not blindly union them with the base tag.",
"items": {
"additionalProperties": false,
"description": "One alternate-definition tag and the reason it differs.",
"properties": {
"note": {
"description": "How this tag differs in definition from the mapped tags.",
"type": "string"
},
"tag": {
"description": "Alternate-definition XBRL tag some filers use as their primary line.",
"type": "string"
}
},
"required": [
"tag",
"note"
],
"type": "object"
},
"type": "array"
},
"tags": {
"description": "XBRL tags this friendly name resolves to under us-gaap, tried in order. Multiple tags cover historical naming changes (e.g., pre- vs post-ASC 606 revenue) and can include a tag SEC has since retired, kept as a last-resort fallback for filers whose history predates its replacement.",
"items": {
"type": "string"
},
"type": "array"
},
"taxonomy": {
"description": "XBRL taxonomy this concept lives in: us-gaap (US filers), ifrs-full (foreign filers), or dei (entity info).",
"enum": [
"us-gaap",
"ifrs-full",
"dei"
],
"type": "string"
},
"unit": {
"description": "Unit of measure (USD, USD/shares, shares, pure). secedgar_fetch_frames accepts both slash and dashed forms.",
"type": "string"
}
},
"required": [
"name",
"label",
"tags",
"taxonomy",
"unit",
"group"
],
"type": "object"
},
"type": "array"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode.",
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"notice": {
"description": "Guidance when no concepts matched — echoes the search term and suggests alternatives.",
"type": "string"
},
"total": {
"description": "Number of concepts matching the filters.",
"type": "number"
}
},
"type": "object"
}
},
{
"description": "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.",
"inputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"properties": {
"filed_after": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"description": "Only include filings filed on or after this date (YYYY-MM-DD). This tool filters by date only with both bounds — pair it with filed_before."
},
"filed_before": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"description": "YYYY-MM-DD",
"pattern": "^\\d{4}-\\d{2}-\\d{2}$",
"type": "string"
}
],
"description": "Only include filings filed on or before this date (YYYY-MM-DD). This tool filters by date only with both bounds — pair it with filed_after."
},
"forms": {
"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.",
"items": {
"type": "string"
},
"type": "array"
},
"limit": {
"default": 20,
"description": "Results per page. Max 100.",
"maximum": 100,
"minimum": 1,
"type": "integer"
},
"offset": {
"default": 0,
"description": "Pagination offset. For sort=relevance on a 2001-onward search, EDGAR pages server-side up to its 10,000-result cap. Everywhere else the offset indexes the rows this call assembled and sorted: a single 100-row 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 total is larger — 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 one window of its total — 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.",
"maximum": 9999,
"minimum": 0,
"type": "integer"
},
"query": {
"anyOf": [
{
"const": "",
"type": "string"
},
{
"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.",
"minLength": 1,
"type": "string"
}
],
"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 to browse by form 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."
},
"sort": {
"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.",
"enum": [
"filing_date_desc",
"filing_date_asc",
"relevance"
],
"type": "string"
}
},
"type": "object"
},
"name": "secedgar_search_filings",
"outputSchema": {
"$schema": "https://json-schema.org/draft/2020-12/schema",
"additionalProperties": false,
"anyOf": [
{
"not": {
"required": [
"error"
]
},
"required": [
"total",
"total_is_exact",
"results",
"effectiveQuery"
]
},
{
"required": [
"error"
]
}
],
"properties": {
"cap": {
"description": "The limit cap applied.",
"type": "number"
},
"dataset": {
"additionalProperties": false,
"description": "Canvas dataframe holding the fetched hits (full-text window, or the full pre-2001 archive match set), each tagged with its `source`. Absent when total ≤ inline limit, canvas is unavailable, or materialization failed. Query with secedgar_dataframe_query SQL.",
"properties": {
"expires_at": {
"description": "ISO 8601 expiry timestamp.",
"type": "string"
},
"name": {
"description": "Dataframe handle (df_XXXXX_XXXXX) — inspect its columns with secedgar_dataframe_describe, then query it with secedgar_dataframe_query.",
"type": "string"
},
"row_count": {
"description": "Rows materialized in the dataframe.",
"type": "number"
},
"truncated": {
"description": "True when more matches exist beyond the materialized set — the full-text window was exceeded, or a pre-2001 archive scan hit its cap. Each row carries a `source` column so provenance survives into secedgar_dataframe_query.",
"type": "boolean"
}
},
"required": [
"name",
"row_count",
"expires_at",
"truncated"
],
"type": "object"
},
"effectiveQuery": {
"description": "The query as executed against EDGAR (ticker/cik: tokens resolved to entity names).",
"type": "string"
},
"error": {
"additionalProperties": {},
"description": "Present when the call failed. Absent on success.",
"properties": {
"code": {
"description": "JSON-RPC error code for this failure.",
"maximum": 9007199254740991,
"minimum": -9007199254740991,
"type": "integer"
},
"data": {
"additionalProperties": {},
"properties": {
"reason": {
"description": "Machine-readable failure mode. Declared by this tool: `invalid_date_range`: Only one of filed_after or filed_before was provided. `unresolved_ticker`: A ticker: targeting token in the query does not resolve to a known company. `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. `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. Other values are possible when a failure originates below the handler.",
"examples": [
"invalid_date_range",
"unresolved_ticker",
"invalid_cik",
"entity_not_found",
"missing_criteria",
"pre2001_full_text_unscoped",
"rate_limited"
],
"type": "string"
},
"recovery": {
"additionalProperties": {},
"description": "Actionable next step for the caller.",
"properties": {
"hint": {
"type": "string"
}
},
"required": [
"hint"
],
"type": "object"
},
"retryable": {
"description": "Whether retrying may succeed.",
"type": "boolean"
}
},
"type": "object"
},
"message": {
"description": "Human-readable description of what went wrong.",
"type": "string"
}
},
"required": [
"code",
"message"
],
"type": "object"
},
"form_distribution": {
"additionalProperties": {
"type": "number"
},
"description": "Count of results by form type. Helps narrow follow-up searches.",
"propertyNames": {
"type": "string"
},
"type": "object"
},
"notice": {
"description": "Guidance when no results were returned — echoes the query and suggests how to broaden.",
"type": "string"
},
"results": {
"description": "Matching filings.",
"items": {
"additionalProperties": false,
"description": "One matching filing hit.",
"properties": {
"accession_number": {
"description": "Filing accession number. Pass to secedgar_get_filing to retrieve the document text.",
"type": "string"
},
"cik": {
"description": "Filing entity CIK, zero-padded to 10 digits.",
"type": "string"
},
"company_name": {
"description": "Filing entity, with ticker/CIK parentheticals stripped.",
"type": "string"
},
"file_description": {
"description": "SEC-provided description of the matching document (e.g., \"EX-99.1\"). Absent when SEC published none, and for pre-2001 archive-sourced rows. A range crossing 2001-01-01 returns both kinds of row together, so this field is populated on source=efts rows only.",
"type": "string"
},
"filing_date": {
"description": "Date the filing was submitted (YYYY-MM-DD).",
"type": "string"
},
"form": {
"description": "Form type (e.g. \"10-K\"). Absent for hits where the index lacks a form tag.",
"type": "string"
},
"location": {
"description": "Business location (state or country code). Absent when SEC has no location for this filer, and for pre-2001 archive-sourced rows. A range crossing 2001-01-01 returns both kinds of row together, so this field is populated on source=efts rows only.",
"type": "string"
},
"period_ending": {
"description": "Period the filing reports on (YYYY-MM-DD). Absent for filings without a reporting period (e.g., proxy statements, ownership reports) and for all pre-2001 archive-sourced rows (source submissions/full-index), which carry no period field. A range crossing 2001-01-01 returns both kinds of row together, so this field is populated on source=efts rows only.",
"type": "string"
},
"sic": {
"description": "SIC industry code for the filer. Absent for filers without a classification, and for pre-2001 archive-sourced rows. A range crossing 2001-01-01 returns both kinds of row together, so this field is populated on source=efts rows only.",
"type": "string"
},
"source": {
"description": "Which EDGAR backend served this row: \"efts\" (2001+ full-text index), \"submissions\" (a pre-2001 entity-scoped filing history), or \"full-index\" (a pre-2001 unscoped quarterly index browse). A date range crossing 2001-01-01 is split at the boundary and returns rows of two sources in one result set, so read this per row rather than per result. Provenance is carried into the canvas dataframe as a `source` column.",
"enum": [
"efts",
"submissions",
"full-index"
],
"type": "string"
},
"ticker": {
"description": "Primary ticker symbol parsed from the EFTS display name. Absent for private filers, foreign filers without a US listing, filings whose display name omits the ticker parenthetical, and all pre-2001 archive-sourced rows. A range crossing 2001-01-01 returns both kinds of row together, so this field is populated on source=efts rows only. For multi-class issuers (e.g., BRK-A / BRK-B), this is the first class listed.",
"type": "string"
}
},
"required": [
"accession_number",
"filing_date",
"company_name",
"cik"
],
"type": "object"
},
"type": "array"
},
"scan": {
"additionalProperties": false,
"description": "Present only on the pre-2001 entity-scoped free-text path, where no full-text index exists and terms are matched by reading documents. Reports the scan's shape so a partial read is never presented as a complete one. Each document read is the whole accession .txt — SEC's original flat-submission format concatenates every exhibit into one file, and pre-1997 filings expose no per-document URL at all — so a match may sit in an attached exhibit rather than the body of the requested form. Absent on every other path.",
"properties": {
"candidates": {
"description": "Filings the form + date pre-filter selected before any document was read.",
"type": "number"
},
"capped": {
"description": "True when candidates exceeded the document cap, so the unscanned remainder may hold further matches — narrow the form or date filter to bring them into range.",
"type": "boolean"
},
"matched": {
"description": "Scanned filings whose text satisfied the query terms.",
"type": "number"
},
"scanned": {
"description": "Candidate documents actually fetched and matched against. Capped at 50 per call.",
"type": "number"
}
},
"required": [
"candidates",
"scanned",
"matched",
"capped"
],
"type": "object"
},
"shown": {
"description": "Number of results shown inline.",
"type": "number"
},
"total": {
"description": "Total matching filings, which can exceed the rows returned inline or materialized. On the full-text (2001+) path this is capped at 10,000; entity targeting (ticker:/cik:) scopes server-side via the EFTS ciks param, so it is the entity's exact match count up to the cap. On a pre-2001 archive path it is the exact count within the scanned window (see total_is_exact). On a range crossing 2001-01-01 it is the sum of both eras' counts.",
"type": "number"
},
"total_is_exact": {
"description": "False when total is a lower bound — the full-text path hit its 10,000 cap, a pre-2001 archive scan hit its page/quarter cap before exhausting the range, or a pre-2001 local text scan hit its document cap (scan.capped).",
"type": "boolean"
},
"truncated": {
"description": "True when results were capped by limit.",
"type": "boolean"
}
},
"type": "object"
}
}
]
}Verify it yourself
curl -s https://api.teppi.xyz/v1/evidence/sha256:fc0e076e6f28c384756c2effa15f06a17ae9d9d5bcc76d470f27d3bac05a64cd | sha256sum