Filing text and segments API reference
The text of US filings by item, and segment, product and geography figures
Overview
Filing text returns what a US company wrote in a 10-K, 10-Q, 20-F or 8-K, cut at the item headings, such as Item 1A Risk Factors or Item 7 Management's Discussion. Segments add the figures a company splits by segment, product or geography to its financial statements. Every request needs a Bearer key, and REST and MCP draw on one credit balance.
Four routes. Two return the text of one filing: one by filing id, one by company, form and fiscal year. One lists the items each form has. The fourth is segments=true on the financials route, which keeps its name and its price. A company is addressed by its Filings API id, for example usa:0000320193, and a filing by its company id, a colon and the SEC accession number.
History goes back five years. A filing whose text is not yet read is 404 sections_, and a period whose own report is not yet read for segments is listed in segments_.
The text routes serve the US, Japan and Korea. A US filing is a 10-K, 10-Q, 20-F or 8-K. A Japanese filing is a YUHO, HANKI, SHIHANKI or RINJI, and a Korean one is a 사업보고서, 반기보고서 or 분기보고서. A form that belongs to another country than the company is 400 invalid_. A company of any other country is 404 not_. A Japanese or Korean filing whose text is not read yet is 404 sections_. Segments are for US companies only.
Base URL: https:/. Each route below is an MCP tool of its own, with the same parameters.
The rows of each financial statement are on the Filings API reference.
Company ids are the ones the Filings API returns from company search.
What every account gets
| What | Every account |
|---|---|
| Filing text, two routes | Included |
| Item list | Included, free |
| Segments on financials | Included |
See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise.
- Billed at the Companies price, $10 per 1,000 calls. Each successful text answer is one call, whatever the item, the size or the format. An 8-K by company, which reads up to the newest 10 8-Ks to find an item, is still one call. An answer with nothing in it is free, and on the text routes nothing found is a 404, which is free too. The item list is free. Errors are not charged.
segments=trueadds no call and no price. Financials with it is one call, the same as without it. An answer with financial rows is charged as one call, whethersegmentshas rows, is empty or is left out.- The text is the filing's own, cut at its item headings. It is not rewritten or summarised. A filing whose items could not be told apart is 404
sections_, never partial text.unavailable - A 10-Q has an Item 1 in Part I and another in Part II. Without
part,item=1returns both. - An 8-K without
itemalso returns the text of its exhibits, asexhibits.truncatedis true on an exhibit whose text was cut. - A segment row gives the figure as filed in the report of its own period:
valueand thefiling_it was filed in. Where a later filing changed the figure,id restatedholds the later figure and the filing it comes from.version=first_gives the figures as filed only.reported - A
restated_row has noonly valueand nofiling_, because no figure as filed is held. Either the report of the period does not hold the member, because a later filing cut the period into other members, or the report is not read yet andid restatedis a later filing's figure, which may not be a restatement at all. segments_lists, newest first, the period ends whose own report is not yet read for segments. Their figures as filed are missing, which is not the same as filing none, and any rows they have areunread restated_.only segmentsis left out when no period has been read and no later filing has a figure.memberandlabelare the company's own words for a segment, product or area, and nothing is matched across companies.conceptis the tag the company used, so two figures of onemeasure, such as revenue with and without intersegment sales, stay apart.percent_is the figure as a percent of the company's consolidated figure for the same concept and period in the filing named byof_ total filing_, two decimals. Members do not always add to 100, because filers add subtotal and consolidated members. It is left out when the filing prints no consolidated figure of that concept and period.id - Segment figures are in whole units of
currency. A figure at a date, such as assets or goodwill, has nostart.
Endpoints
Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.
Get the text of a filing by item
GET /v1/filings/{filing_id}/sections
The text of one filing, cut at the item headings: every item, or one item with item. A US 10-K, 10-Q, 20-F or 8-K, or a Japanese or Korean report. A filing whose items could not be told apart is 404 sections_, never partial text.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
filing_ | path | Yes | string | The filing id: the company id, a colon and the SEC accession number, for example usa:0000320193:0000320193-26-000026. The Filings API lists them. |
item | query | No | string | One item by its number, for example 1A or 7. An 8-K item looks like 2.02. Left out, every item is returned. An item the filing does not have is 404 item_. |
part | query | No | string | The part (I to IV). A 10-Q has an Item 1 in Part I and another in Part II; without part, item returns both. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | The filing id. On financials, the company id. |
form | string | Always | The form of the filing, for example 10-K. |
sections | list of object | Always | The items of the filing, in filing order. |
sections[].item | string | Always | The item number, for example 1A, or 2.02 on an 8-K. |
sections[].title | string | Always | The item's heading, for example Risk Factors. |
sections[].text | string | Always | The text of the item, as filed. |
sections[].part | string | Optional | The part the item sits in, I to IV. Left out when the form has no parts. |
exhibits | list of object | Optional | The exhibit files of an 8-K, as text. Sent when item is left out. |
exhibits[].type | string | Always | The exhibit type, for example EX-99.1. |
exhibits[].name | string | Always | The exhibit's file name. |
exhibits[].text | string | Always | The exhibit's text. |
exhibits[].truncated | boolean | Optional | True when the text was cut. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-26-000026/sections?item=1A"{
"id": "usa:0000320193:0000320193-26-000026",
"form": "10-K",
"sections": [
{
"item": "1A",
"title": "Risk Factors",
"text": "The following summarizes factors that could have a material adverse effect on the Company’s business, reputation, results of operations, financial condition and…",
"part": "I"
}
]
}Get a company's filing text by form and year
GET /v1/companies/{company_id}/sections
The same text as the filing route, found by company, form and fiscal year, so no filing id is needed. Without year it is the newest filing of that form. For an 8-K with item, it is the newest of the company's last 10 8-Ks that has the item.
Use quarter with form=10-Q to pick a quarter. It is 400 invalid_ with any other form.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
company_ | path | Yes | string | The company id, for example usa:0000320193. A ticker alias such as usa:AAPL is accepted. |
form | query | Yes | one of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서 | The form, as the company's country names it: 10-K, 10-Q, 20-F or 8-K for the US; YUHO, HANKI, SHIHANKI or RINJI for Japan; 사업보고서, 반기보고서 or 분기보고서 for Korea. Any other value is 400 invalid_. |
year | query | No | integer | Fiscal year of a 10-K, 10-Q or 20-F; the year it was filed for an 8-K. Omit it for the newest filing. |
quarter | query | No | integer | Fiscal quarter, of a quarterly report only (10-Q, SHIHANKI, 분기보고서). |
item | query | No | string | One item, for example 1A. For an 8-K the answer is the newest of the company's last 10 8-Ks that has the item (an 8-K reports one event, so the newest one often lacks it); without item it is the newest 8-K. |
part | query | No | string | The part, I to IV. A 10-Q has an Item 1 in Part I and another in Part II; without part, item returns both. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | The filing id. On financials, the company id. |
form | string | Always | The form of the filing, for example 10-K. |
sections | list of object | Always | The items of the filing, in filing order. |
sections[].item | string | Always | The item number, for example 1A, or 2.02 on an 8-K. |
sections[].title | string | Always | The item's heading, for example Risk Factors. |
sections[].text | string | Always | The text of the item, as filed. |
sections[].part | string | Optional | The part the item sits in, I to IV. Left out when the form has no parts. |
exhibits | list of object | Optional | The exhibit files of an 8-K, as text. Sent when item is left out. |
exhibits[].type | string | Always | The exhibit type, for example EX-99.1. |
exhibits[].name | string | Always | The exhibit's file name. |
exhibits[].text | string | Always | The exhibit's text. |
exhibits[].truncated | boolean | Optional | True when the text was cut. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/companies/usa:0000320193/sections?form=8-K"{
"id": "usa:0000320193:0001140361-26-042798",
"form": "8-K",
"sections": [
{
"item": "8.01",
"title": "Other Events",
"text": "Other Events.\nOn November 9, 2026, Apple Inc. (“Apple”) consummated the issuance and sale of $500,000,000 aggregate principal amount of its Floating Rate Notes…"
},
{
"item": "9.01",
"title": "Financial Statements and Exhibits",
"text": "Financial Statements and Exhibits.\n(d) Exhibits.\nExhibit\nNumber\nExhibit Description\n1.1 Underwriting Agreement, dated November 5, 2026, among Apple Inc. and Gol…"
}
],
"exhibits": [
{
"type": "EX-1.1",
"name": "ef20085077_ex1-1.htm",
"text": "EX-1.1 2 ef20085077_ex1-1.htm EXHIBIT 1.1\nExhibit 1.1\nApple Inc.\n$500,000,000 Floating Rate Notes due 2028\n$750,000,000 Floating Rate Notes due 2029\n$1,000,000,…"
},
{
"type": "EX-4.1",
"name": "ef20085077_ex4-1.htm",
"text": "EX-4.1 3 ef20085077_ex4-1.htm EXHIBIT 4.1\nExhibit 4.1\nAPPLE INC.\nOfficer’s Certificate\nPursuant to Sections 102 and 301 of the Indenture, dated as of November 1…"
}
]
}List the items of each form
GET /v1/filings/sections/items
The items the text routes can return for each form: item, part and title. Free: this route is not charged.
Ask for the items first, then pass one of them as item on the text routes.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
form | query | No | one of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서 | One form's items, from any of the three lists above. Without it, the items of the four US forms. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
items | list of object | Always | The items, form by form. |
items[].form | one of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서 | Always | The form the item belongs to. |
items[].item | string | Always | The item number, as item takes it. |
items[].title | string | Always | The item's heading. |
items[].part | string | Optional | The part the item sits in. Left out when the form has no parts. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/filings/sections/items?form=10-K"{
"items": [
{
"form": "10-K",
"item": "1",
"title": "Business",
"part": "I"
},
{
"form": "10-K",
"item": "1A",
"title": "Risk Factors",
"part": "I"
},
{
"form": "10-K",
"item": "1B",
"title": "Unresolved Staff Comments",
"part": "I"
},
{
"form": "10-K",
"item": "1C",
"title": "Cybersecurity",
"part": "I"
}
]
}Get segments with the financial statements
GET /v1/companies/{company_id}/financials
segments=true adds segments to the financial statements answer: the revenue, operating income, assets, capex, depreciation, goodwill and long-lived assets that a company breaks down by segment, product or geography. It is the same route and the same price as financials without it. The rows of each statement are on the Filings API page.
Without segments=true this is the financials route of the Filings API and the answer has no segments. With it, segments is sent when a period or a later filing gives a figure. The newest period comes first, and revenue comes before the other measures.
The segments follow the periods in the answer, so period, fiscal_, as_ and version cut them the same way.
MCP: tool filings_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
company_ | path | Yes | string | The company id, for example usa:0000320193. A ticker alias such as usa:AAPL is accepted. |
fields | query | No | string | Comma-separated standard item names, or all. Without it, 15 common items. |
statement | query | No | one of income, balance, cash_flow, per_share, shares, other | All items of one statement: income, balance, cash_, per_, shares or other. |
period | query | No | one of annual, semiannual, quarterly | annual by default, semiannual or quarterly, as far as the registry publishes it. US companies have no semiannual reports. |
fiscal_ | query | No | integer | One fiscal year. |
basis | query | No | one of consolidated, standalone | consolidated or standalone. |
version | query | No | one of latest, first_reported | latest by default, or first_. |
as_ | query | No | date | Figures as known on this day (YYYY-MM-DD). |
segments | query | No | boolean | true adds segments: the revenue, operating income, assets, capex, depreciation, goodwill and long-lived assets that filers break down by segment, product or geography, for the periods in the answer. Labels are the company's own, in the filing's language, and each figure carries its currency. A figure is given as filed in the report of its own period (value, filing_) and, where a later filing changed it, as restated with that filing; version=first_ gives the figures as filed only. A period whose report has not been read for segments is named in segments_, and its rows come from later filings. A company of a country the breakdown does not cover is 404 not_. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
id | string | Always | The filing id. On financials, the company id. |
currency | string | Optional | Currency of the statement amounts. |
basis | one of consolidated, standalone | Optional | consolidated or standalone. |
from_ | integer | Optional | The first fiscal year the answer holds, sent when its history was cut. Left out otherwise. |
annual | list of object | Optional | The annual rows, newest first. The row key is semiannual or quarterly when period asks for it. The items in a row are on the Filings API page. |
semiannual | list of object | Optional | The half-year rows, when period=semiannual. |
quarterly | list of object | Optional | The quarterly rows, when period=quarterly. |
as_ | date | Optional | The day the figures are as of. |
segments | list of object | Optional | The breakdowns for the periods in the answer, newest period first. Left out when no period has been read and no later filing has a figure. |
segments[].end | date | Always | End of the period, or the date of the figure. |
segments[].start | date | Optional | Start of the period. Left out for a figure at a date, such as assets or goodwill. |
segments[].measure | one of revenue, operating_income, assets, capex, depreciation, goodwill, long_lived_assets | Always | What is measured: revenue, operating_, assets, capex, depreciation, goodwill or long_. |
segments[].axis | one of segment, product, geography | Always | How the company splits it: segment, product or geography. |
segments[].member | string | Always | The company's name for the segment, product or area, as tagged in its filing. |
segments[].label | string | Optional | The company's own wording for the member. |
segments[].concept | string | Always | The tag the company used for the figure. |
segments[].value | string | Optional | The figure as filed in the report of this period (filing_). Left out for a restated_ member. |
segments[].filing_ | string | Optional | The filing value was filed in: the first report of this period. |
segments[].currency | string | Always | Currency of the figure. |
segments[].percent_ | string | Optional | The value as a percent of the company's consolidated figure for the same concept, period and currency in filing_, two decimals, half away from zero ("37.42"). It is the filing's own undimensioned figure, never the sum of the members: filers add subtotal and consolidated members, and some tag segment profit before unallocated costs with the consolidated concept, so members do not always add to 100. Negative when the value and the total have opposite signs (a loss-making segment of a profitable company); a loss-making segment of a company with a consolidated loss is positive. Left out when the filing prints no consolidated figure of that concept and period (for example the total is tagged with another concept), the total is zero, or the currencies differ. |
segments[].restated | object | Optional | The figure a later filing gives, with that filing, where it changed the figure as filed. On a restated_ row it is the only figure held, and it may not be a restatement. |
segments[].restated.value | string | Always | The restated figure, in whole units of currency. |
segments[].restated.filing_ | string | Always | The later filing the restated figure comes from. |
segments[].restated.percent_ | string | Optional | The value as a percent of the company's consolidated figure for the same concept, period and currency in filing_, two decimals, half away from zero ("37.42"). It is the filing's own undimensioned figure, never the sum of the members: filers add subtotal and consolidated members, and some tag segment profit before unallocated costs with the consolidated concept, so members do not always add to 100. Negative when the value and the total have opposite signs (a loss-making segment of a profitable company); a loss-making segment of a company with a consolidated loss is positive. Left out when the filing prints no consolidated figure of that concept and period (for example the total is tagged with another concept), the total is zero, or the currencies differ. |
segments[].restated_ | always true | Optional | true when no figure as filed is held: the report of this period does not hold the member (a later filing re-cut the period into other members), or the report is not loaded yet (the period is in segments_). value and filing_ are left out and restated is the only figure, a later filing's, which in the second case may not be a restatement at all. When the report is loaded the row gains value and filing_. |
segments_ | list of date | Optional | End dates, newest first, of the periods whose own report has not been read for segments yet. Their figures as filed are missing, which is not the same as filing none; any rows they have are restated_, from later filings. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/companies/usa:0001260221/financials?segments=true&period=annual&fiscal_year=2024&statement=income"{
"id": "usa:0001260221",
"currency": "USD",
"annual": [
{
"fy": 2024,
"end": "2024-09-30",
"form": "10-K",
"derived": [],
"revenue": "7940000000",
"gross_profit": "4672000000",
"operating_income": "3531000000",
"net_income": "1714000000"
}
],
"as_of": "2026-11-10",
"segments": [
{
"end": "2024-09-30",
"start": "2023-10-01",
"measure": "revenue",
"axis": "geography",
"member": "country:US",
"label": "UNITED STATES",
"concept": "us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax",
"value": "5032000000",
"filing_id": "usa:0001260221:0001260221-24-000083",
"currency": "USD",
"percent_of_total": "63.38"
},
{
"end": "2024-09-30",
"start": "2023-10-01",
"measure": "revenue",
"axis": "segment",
"member": "tdg:PowerAndControlMember",
"label": "Power And Control [Member]",
"concept": "us-gaap:Revenues",
"value": "3941000000",
"filing_id": "usa:0001260221:0001260221-24-000083",
"currency": "USD",
"percent_of_total": "49.63",
"restated": {
"value": "3966000000",
"filing_id": "usa:0001260221:0001260221-25-000081",
"percent_of_total": "49.95"
}
},
{
"end": "2024-09-30",
"start": "2023-10-01",
"measure": "revenue",
"axis": "geography",
"member": "country:US",
"label": "UNITED STATES",
"concept": "us-gaap:Revenues",
"currency": "USD",
"restated": {
"value": "5032000000",
"filing_id": "usa:0001260221:0001260221-25-000081",
"percent_of_total": "63.38"
},
"restated_only": true
},
{
"end": "2024-09-30",
"measure": "assets",
"axis": "segment",
"member": "tdg:PowerAndControlMember",
"label": "Power And Control [Member]",
"concept": "us-gaap:Assets",
"value": "9139000000",
"filing_id": "usa:0001260221:0001260221-24-000083",
"currency": "USD",
"percent_of_total": "35.72",
"restated": {
"value": "9180000000",
"filing_id": "usa:0001260221:0001260221-25-000014",
"percent_of_total": "35.88"
}
}
]
}Errors
Errors use the shared problem shape with a request_. See Errors and credits for the shape and the credit headers. Failed requests are not charged.
| Code | Status | Meaning |
|---|---|---|
invalid_ | 400 | A parameter is missing, unknown, repeated or outside its range. |
company_ | 404 | No company matches the id. |
filing_ | 404 | No filing matches the id, or the company has no filing of that form and period. |
item_ | 404 | The filing has no such item. For an 8-K asked by company, none of the newest 10 8-Ks has it. |
sections_ | 404 | No text is served for this filing: its text is not read yet, it is not a US filing, or its items could not be told apart. |
segments_ | 404 | The segments of this company have not been read yet. |
not_ | 404 | The market, country or company is not covered yet. |
insufficient_ | 402 | Your credit balance is less than the request costs. |
company_ | 503 | The filings behind this route cannot be read right now. Try again shortly. |
Was this page helpful?