Browse all documentation

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_unavailable, and a period whose own report is not yet read for segments is listed in segments_unread.

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_query. A company of any other country is 404 not_covered. A Japanese or Korean filing whose text is not read yet is 404 sections_unavailable. Segments are for US companies only.

Base URL: https://api.narwhalapi.com. 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

WhatEvery account
Filing text, two routesIncluded
Item listIncluded, free
Segments on financialsIncluded

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=true adds 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, whether segments has 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_unavailable, never partial text.
  • A 10-Q has an Item 1 in Part I and another in Part II. Without part, item=1 returns both.
  • An 8-K without item also returns the text of its exhibits, as exhibits. truncated is true on an exhibit whose text was cut.
  • A segment row gives the figure as filed in the report of its own period: value and the filing_id it was filed in. Where a later filing changed the figure, restated holds the later figure and the filing it comes from. version=first_reported gives the figures as filed only.
  • A restated_only row has no value and no filing_id, 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 and restated is a later filing's figure, which may not be a restatement at all.
  • segments_unread 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 are restated_only. segments is left out when no period has been read and no later filing has a figure.
  • member and label are the company's own words for a segment, product or area, and nothing is matched across companies. concept is the tag the company used, so two figures of one measure, such as revenue with and without intersegment sales, stay apart.
  • percent_of_total is the figure as a percent of the company's consolidated figure for the same concept and period in the filing named by filing_id, 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.
  • Segment figures are in whole units of currency. A figure at a date, such as assets or goodwill, has no start.

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_unavailable, never partial text.

MCP: tool filings_get_sections.

Parameters

ParameterWhereRequiredTypeMeaning
filing_idpathYesstringThe filing id: the company id, a colon and the SEC accession number, for example usa:0000320193:0000320193-26-000026. The Filings API lists them.
itemqueryNostringOne 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_not_found.
partqueryNostringThe 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

FieldTypeSentMeaning
idstringAlwaysThe filing id. On financials, the company id.
formstringAlwaysThe form of the filing, for example 10-K.
sectionslist of objectAlwaysThe items of the filing, in filing order.
sections[].itemstringAlwaysThe item number, for example 1A, or 2.02 on an 8-K.
sections[].titlestringAlwaysThe item's heading, for example Risk Factors.
sections[].textstringAlwaysThe text of the item, as filed.
sections[].partstringOptionalThe part the item sits in, I to IV. Left out when the form has no parts.
exhibitslist of objectOptionalThe exhibit files of an 8-K, as text. Sent when item is left out.
exhibits[].typestringAlwaysThe exhibit type, for example EX-99.1.
exhibits[].namestringAlwaysThe exhibit's file name.
exhibits[].textstringAlwaysThe exhibit's text.
exhibits[].truncatedbooleanOptionalTrue when the text was cut.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-26-000026/sections?item=1A"
Example response
{
  "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_query with any other form.

MCP: tool filings_get_company_sections.

Parameters

ParameterWhereRequiredTypeMeaning
company_idpathYesstringThe company id, for example usa:0000320193. A ticker alias such as usa:AAPL is accepted.
formqueryYesone 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_query.
yearqueryNointegerFiscal 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.
quarterqueryNointegerFiscal quarter, of a quarterly report only (10-Q, SHIHANKI, 분기보고서).
itemqueryNostringOne 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.
partqueryNostringThe 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

FieldTypeSentMeaning
idstringAlwaysThe filing id. On financials, the company id.
formstringAlwaysThe form of the filing, for example 10-K.
sectionslist of objectAlwaysThe items of the filing, in filing order.
sections[].itemstringAlwaysThe item number, for example 1A, or 2.02 on an 8-K.
sections[].titlestringAlwaysThe item's heading, for example Risk Factors.
sections[].textstringAlwaysThe text of the item, as filed.
sections[].partstringOptionalThe part the item sits in, I to IV. Left out when the form has no parts.
exhibitslist of objectOptionalThe exhibit files of an 8-K, as text. Sent when item is left out.
exhibits[].typestringAlwaysThe exhibit type, for example EX-99.1.
exhibits[].namestringAlwaysThe exhibit's file name.
exhibits[].textstringAlwaysThe exhibit's text.
exhibits[].truncatedbooleanOptionalTrue when the text was cut.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/companies/usa:0000320193/sections?form=8-K"
Example response
{
  "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_list_section_items.

Parameters

ParameterWhereRequiredTypeMeaning
formqueryNoone 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

FieldTypeSentMeaning
itemslist of objectAlwaysThe items, form by form.
items[].formone of 10-K, 10-Q, 20-F, 8-K, YUHO, HANKI, SHIHANKI, RINJI, 사업보고서, 반기보고서, 분기보고서AlwaysThe form the item belongs to.
items[].itemstringAlwaysThe item number, as item takes it.
items[].titlestringAlwaysThe item's heading.
items[].partstringOptionalThe part the item sits in. Left out when the form has no parts.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/filings/sections/items?form=10-K"
Example response
{
  "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_year, as_of and version cut them the same way.

MCP: tool filings_get_financials.

Parameters

ParameterWhereRequiredTypeMeaning
company_idpathYesstringThe company id, for example usa:0000320193. A ticker alias such as usa:AAPL is accepted.
fieldsqueryNostringComma-separated standard item names, or all. Without it, 15 common items.
statementqueryNoone of income, balance, cash_flow, per_share, shares, otherAll items of one statement: income, balance, cash_flow, per_share, shares or other.
periodqueryNoone of annual, semiannual, quarterlyannual by default, semiannual or quarterly, as far as the registry publishes it. US companies have no semiannual reports.
fiscal_yearqueryNointegerOne fiscal year.
basisqueryNoone of consolidated, standaloneconsolidated or standalone.
versionqueryNoone of latest, first_reportedlatest by default, or first_reported.
as_ofqueryNodateFigures as known on this day (YYYY-MM-DD).
segmentsqueryNobooleantrue 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_id) and, where a later filing changed it, as restated with that filing; version=first_reported gives the figures as filed only. A period whose report has not been read for segments is named in segments_unread, and its rows come from later filings. A company of a country the breakdown does not cover is 404 not_covered.

Response fields

FieldTypeSentMeaning
idstringAlwaysThe filing id. On financials, the company id.
currencystringOptionalCurrency of the statement amounts.
basisone of consolidated, standaloneOptionalconsolidated or standalone.
from_fyintegerOptionalThe first fiscal year the answer holds, sent when its history was cut. Left out otherwise.
annuallist of objectOptionalThe 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.
semiannuallist of objectOptionalThe half-year rows, when period=semiannual.
quarterlylist of objectOptionalThe quarterly rows, when period=quarterly.
as_ofdateOptionalThe day the figures are as of.
segmentslist of objectOptionalThe 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[].enddateAlwaysEnd of the period, or the date of the figure.
segments[].startdateOptionalStart of the period. Left out for a figure at a date, such as assets or goodwill.
segments[].measureone of revenue, operating_income, assets, capex, depreciation, goodwill, long_lived_assetsAlwaysWhat is measured: revenue, operating_income, assets, capex, depreciation, goodwill or long_lived_assets.
segments[].axisone of segment, product, geographyAlwaysHow the company splits it: segment, product or geography.
segments[].memberstringAlwaysThe company's name for the segment, product or area, as tagged in its filing.
segments[].labelstringOptionalThe company's own wording for the member.
segments[].conceptstringAlwaysThe tag the company used for the figure.
segments[].valuestringOptionalThe figure as filed in the report of this period (filing_id). Left out for a restated_only member.
segments[].filing_idstringOptionalThe filing value was filed in: the first report of this period.
segments[].currencystringAlwaysCurrency of the figure.
segments[].percent_of_totalstringOptionalThe value as a percent of the company's consolidated figure for the same concept, period and currency in filing_id, 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[].restatedobjectOptionalThe figure a later filing gives, with that filing, where it changed the figure as filed. On a restated_only row it is the only figure held, and it may not be a restatement.
segments[].restated.valuestringAlwaysThe restated figure, in whole units of currency.
segments[].restated.filing_idstringAlwaysThe later filing the restated figure comes from.
segments[].restated.percent_of_totalstringOptionalThe value as a percent of the company's consolidated figure for the same concept, period and currency in filing_id, 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_onlyalways trueOptionaltrue 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_unread). value and filing_id 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_id.
segments_unreadlist of dateOptionalEnd 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_only, from later filings.
Request
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"
Example response
{
  "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_id. See Errors and credits for the shape and the credit headers. Failed requests are not charged.

CodeStatusMeaning
invalid_query400A parameter is missing, unknown, repeated or outside its range.
company_not_found404No company matches the id.
filing_not_found404No filing matches the id, or the company has no filing of that form and period.
item_not_found404The filing has no such item. For an 8-K asked by company, none of the newest 10 8-Ks has it.
sections_unavailable404No 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_unavailable404The segments of this company have not been read yet.
not_covered404The market, country or company is not covered yet.
insufficient_credits402Your credit balance is less than the request costs.
company_data_unavailable503The filings behind this route cannot be read right now. Try again shortly.

Was this page helpful?