Filings API reference

Operations

Every request needs a Bearer key; REST requests use Authorization: Bearer $NARWHAL_API_KEY. Authentication

Company and filing IDs

Use the company id returned by search; Taiwan IDs have the prefix twn: followed by the code search returns.

A filing ID combines the company ID and the registry's accession number, separated by a colon, for example usa:0000320193:0000320193-25-000079.

A ticker alias such as usa:AAPL is accepted in a company path and resolves to the company ID.

Search companies

Find companies by name, ticker or code, with optional country and registry filters. Use as_of to select the ticker in force on a particular date.

• q: Company name, ticker or code, up to 200 characters.
• country: Uppercase alpha-3 country code.
• registry: Lowercase registry code, such as usa, jpn or kor.
• as_of: Date used to select the ticker in force.
• lang: en by default, or original.
• limit: 1 to 100 results, default 20.

The companies list contains company identity and listing details. matched explains the match with id, code, name, former_code or former_name; a former name and a true delisted flag appear where applicable. Without q, the response also includes coverage, the number of companies loaded per registry.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies?q=AAPL&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "companies": [
    {
      "id": "usa:0000320193",
      "name": "Apple Inc.",
      "country": "USA",
      "mic": "XNAS",
      "code": "AAPL",
      "matched": "code"
    }
  ]
}

Get a company

Read a company's identity, reporting standard, name history, securities and related companies.

• as_of: Date used to select the ticker in force.
• lang: en by default, or original.

Identity includes available legal identifiers, industry classification and status details. fiscal_year_end uses MMDD, such as 0926 for 26 September, and standard identifies us_gaap, ifrs, j_gaap, jmis or k_gaap. names records former names with dates; securities describes share classes, types, identifiers and dated listings; related identifies cross-listed, successor or predecessor companies. These three fields are always lists.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "name": "Apple Inc.",
  "country": "USA",
  "fiscal_year_end": "0926",
  "standard": "us_gaap",
  "industry": {
    "isic": "2620",
    "sector": "Manufacturing",
    "industry": "Manufacture of computer, electronic and optical products",
    "source_scheme": "us_sic",
    "source_code": "3571"
  },
  "names": [
    {
      "name": "APPLE INC",
      "from": "2007-01-10",
      "to": "2019-08-05"
    },
    {
      "name": "APPLE COMPUTER INC",
      "from": "1994-01-26",
      "to": "2007-01-04"
    },
    {
      "name": "APPLE COMPUTER INC/ FA",
      "from": "1997-07-28",
      "to": "1997-07-28"
    }
  ],
  "securities": [
    {
      "class": "common",
      "type": "common",
      "primary": true,
      "listings": [
        {
          "mic": "XNAS",
          "code": "AAPL",
          "from": "2026-10-20"
        }
      ]
    }
  ],
  "related": []
}

Get financials

Read standard financial items for a company's fiscal periods, newest first. The response uses annual, semiannual or quarterly as its row key, according to period.

• fields: Comma-separated standard item names, or all; defaults to 15 common items.
• statement: All items from income, balance, cash_flow, per_share, shares or other.
• period: annual by default, semiannual or quarterly, subject to registry and plan limits.
• fiscal_year: One fiscal year, within the plan's history window.
• basis: consolidated or standalone.
• version: latest by default; first_reported requires Pro.
• as_of: Figures as known on the specified date; requires Pro.

There are 77 standard items: 29 income statement, 28 balance sheet, 14 cash flow, 3 per share and 3 shares items. Select names with fields, use fields=all for every item, or select a statement with statement. The default 15 are revenue, gross_profit, operating_income, net_income, cash, total_assets, total_debt, total_liabilities, total_equity, operating_cash_flow, capex, free_cash_flow, eps_diluted, dividend_per_share and shares_outstanding. An unknown field name returns 400 unknown_field.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?fields=revenue,net_income,total_assets,eps_diluted" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "currency": "USD",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "derived": [],
      "revenue": "416161000000",
      "net_income": "112010000000",
      "total_assets": "359241000000",
      "eps_diluted": "7.46"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "derived": [],
      "revenue": "391035000000",
      "net_income": "93736000000",
      "total_assets": "364980000000",
      "eps_diluted": "6.08"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "derived": [],
      "revenue": "383285000000",
      "net_income": "96995000000",
      "total_assets": "352583000000",
      "eps_diluted": "6.13"
    }
  ]
}

Amounts are decimal strings in the filing's own currency, without conversion or scaling. Missing items are omitted, and a reported zero remains "0". Each row identifies its fiscal year and period end, with a fiscal quarter or half where relevant; derived lists items Narwhal computed, such as free_cash_flow. The official filing is always the source of truth.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/financials?statement=per_share" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "from_fy": 2023,
  "annual": [
    {
      "fy": 2025,
      "end": "2025-09-27",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "7.46",
      "dividend_per_share": "1.02"
    },
    {
      "fy": 2024,
      "end": "2024-09-28",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.08",
      "dividend_per_share": "0.98"
    },
    {
      "fy": 2023,
      "end": "2023-09-30",
      "currency": "USD",
      "derived": [],
      "eps_diluted": "6.13",
      "dividend_per_share": "0.94"
    }
  ]
}

Japan publishes annual and semiannual reports, with no quarterly reports. US companies publish annual and quarterly reports, with no semiannual reports; Taiwan also has no semiannual reports. EU/EEA reports are annual. A period the registry does not publish returns 404 period_not_published, with a detail that names the period to use.

List company filings

Read a company's filings with filters for type, form and filing dates.

• type: annual, semiannual, quarterly, event, ownership, insider or other.
• form: Exact form name, such as 10-K, up to 20 characters.
• filed_from: Start filing date.
• filed_to: End filing date.
• include_amendments: Whether to include amendments, default false.
• cursor: Cursor for the next page, with the same filters.
• limit: 1 to 200 results, default 50.
• lang: en by default, or original.

Rows identify the filing, filing date, form, type and period end, with a title when the registry supplies one. Results are newest first; use next_cursor for the next page, with null on the last page. filed_from is echoed when the plan raises the start date.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/filings?type=annual&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "filings": [
    {
      "id": "usa:0000320193:0000320193-25-000079",
      "filed": "2025-10-31",
      "form": "10-K",
      "type": "annual",
      "period_end": "2025-09-27"
    },
    {
      "id": "usa:0000320193:0000320193-24-000123",
      "filed": "2024-11-01",
      "form": "10-K",
      "type": "annual",
      "period_end": "2024-09-28"
    }
  ],
  "next_cursor": "eyJpIjo0MTUwNjcsImtpbmQiOiJmaWxpbmdzIiwicSI6IjExYzkyYjY4YWJjZTMyM2YiLCJ0IjoiMjAyNC0xMS0wMVQxMDowMTozNiswMDowMCIsInYiOjF9.j2L56WYc-pkZ4UoI0z1vAN4htuG4nzEDOJUTtT_CZOY"
}

Get a filing

Read one filing's metadata and official registry link; lang accepts en by default or original.

The response identifies the filing and company, with filer_id when the filer differs. It includes form, type, title, fiscal year, period end and the UTC filed_at timestamp where available. fp identifies FY, H1, H2 or Q1 to Q4; url links to the registry's page for the official filing. amends identifies the filing being amended, and withdrawn appears only when true.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193:0000320193-25-000079",
  "company_id": "usa:0000320193",
  "form": "10-K",
  "type": "annual",
  "fy": 2025,
  "fp": "FY",
  "period_end": "2025-09-27",
  "filed_at": "2025-10-31T10:01:26Z",
  "url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/0000320193-25-000079-index.htm"
}

Latest filings

Read the newest filings across companies, with company_id on each row.

• country: Uppercase alpha-3 country code.
• type: annual, semiannual, quarterly, event, ownership, insider or other.
• limit: 1 to 200 results, default 50.
• lang: en by default, or original.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/latest?country=USA&type=annual&limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "filings": [
    {
      "id": "usa:0001888525:0001213900-26-112533",
      "filed": "2026-10-26",
      "form": "20-F",
      "type": "annual",
      "title": "ANNUAL REPORT",
      "company_id": "usa:0001888525"
    },
    {
      "id": "usa:0001901203:0001213900-26-112531",
      "filed": "2026-10-26",
      "form": "10-K/A",
      "type": "annual",
      "title": "AMENDMENT NO. 2 TO FORM 10-K",
      "company_id": "usa:0001901203"
    }
  ]
}

Holders of 5% or more

Read holders reported in ownership filings from the US, Japan and Korea. The list uses each holder's latest report and removes holders that have exited.

• security: Share class, up to 40 characters.
• lang: en by default, or original.
• limit: 1 to 500 results, default 100.

Each row identifies the holder, percentage, shares, event date, filing date, filing ID and security where available. The list is not paged. filed_from is echoed when the plan raises the start date.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/companies/usa:0000320193/holders?limit=2" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "id": "usa:0000320193",
  "filed_from": "2023-10-27",
  "holders": [
    {
      "holder": "Vanguard Capital Management",
      "percent": "7.48",
      "shares": "1099168953",
      "event_date": "2026-03-31",
      "filed": "2026-04-30",
      "filing_id": "usa:0000320193:0002100119-26-000139",
      "security": {
        "class": "common"
      }
    }
  ]
}

Financials as reported

Read the financial facts of one filing exactly as tagged, grouped by concept. This operation is open on every plan within the filing lookup.

Each entry in concepts has taxonomy, concept, label, unit and a values list. Each value has start, end and value where present.

curl --request GET \
  --url "https://api.narwhalapi.com/v1/filings/usa:0000320193:0000320193-25-000079/financials/as-reported" \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

{
  "concepts": [
    {
      "taxonomy": "us-gaap",
      "concept": "Revenues",
      "label": "Revenues",
      "unit": "USD",
      "values": [
        {
          "start": "2023-10-01",
          "end": "2024-09-28",
          "value": "391035000000"
        },
        {
          "start": "2022-09-25",
          "end": "2023-09-30",
          "value": "383285000000"
        }
      ]
    }
  ]
}

US filings only; Japan and Korea filings return 404 as_reported_unavailable. A filing can contain thousands of facts, so the response can be several hundred kilobytes. Results are not paged.

Plan limits

All operations and standard items are open on every plan; the plan sets history and delivery.

A request that only starts too early is clipped to the plan's window, with from_fy for financials or filed_from for filings and holders. Filing and holder windows use calendar years; Free delivery includes only filings filed before 00:00 UTC today.

Requests for quarterly or semiannual financials on Free, a fiscal_year before the history window, a filed_to before the window, or financials with version=first_reported or as_of below Pro return 403 plan_upgrade_required before any quota is charged.

Response conventions

• Numbers are decimal strings.
• Missing scalar fields are omitted, never null.
• Lists are always present, with [] when empty.
• Flags such as delisted and withdrawn appear only when true.
• next_cursor is null on the last page.
• lang=original returns names and titles in the registry's own language where available; the default is en.

Errors

• 400 invalid_query The query is invalid.
• 400 unknown_field A name in fields is not a standard financial item.
• 400 invalid_cursor The cursor is malformed or was issued for different filters.
• 401 invalid_api_key The API key is invalid.
• 403 plan_upgrade_required The requested history, period or financials version is outside the plan.
• 404 company_not_found The company was not found.
• 404 filing_not_found The filing was not found.
• 404 period_not_published The registry does not publish the requested period; the detail names the period to use.
• 404 as_reported_unavailable As-reported financial facts are unavailable for the filing.
• 429 rate_limit_exceeded The request rate limit has been exceeded.
• 429 quota_exhausted The request quota has been exhausted.
• 503 database_unavailable The data store is unavailable; retry the request.

Errors use the standard problem shape. Errors and quota

Authentication documents Bearer keys, errors documents the standard problem shape, and MCP documents tool access. Authentication · Errors and quota · MCP