Browse all documentation

Company screener API reference

Find companies by filters on their newest fundamentals, and read line items for up to 10 companies

Overview

The screener finds listed companies whose newest financial figures meet the conditions you set, across the filings registries Narwhal holds. You send filters such as a net margin above 20 percent, and it returns the matching companies with the figures you asked for. Every request needs a Bearer key, and REST and MCP draw on one credit balance.

Three routes. The first screens. The second lists every field, operator, currency and registry a screen can use, and costs nothing. The third returns chosen line items for up to 10 companies you already know, in one request. A company is addressed by its Filings API id, for example usa:0000320193.

Each company has one row per basis: its newest fiscal year (annual), its newest quarter (quarterly) or its last four quarters added up (ttm). The rows are rebuilt every night from the filings, and built_at on the filter list says when. Amounts are in the company's own currency and are not converted, so a filter or an order on an amount needs currency. Each amount also has a twin named with the suffix _usd, for example revenue_usd, which needs no currency. Today the _usd figures are filled only for companies that report in US dollars, so a _usd filter returns only those companies.

The screener is built on fundamentals. The price fields are filled from the daily close once that job has run for the company, and are empty until then. A figure the company has not reported is left out of its row, and a company with no value for a field never matches a filter on it.

Base URL: https://api.narwhalapi.com. Each route below is an MCP tool of its own, with the same parameters.

The financial statements of one company are on the Filings API reference.

Company ids are the ones the Filings API returns from company search.

What every account gets

WhatEvery account
ScreenIncluded. One call for every 10 companies returned, rounded up
Filter listIncluded. Free
Line itemsIncluded. One call for each company found, at most 10

See pricing for what a call costs. A request is charged at the price of its API unless a route says otherwise.

  • A screen is billed by the companies in the page it returns, at the Companies price of $10 per 1,000 calls, which is $0.01 a call: one call for every 10 companies, rounded up. 1 to 10 companies is 1 call ($0.01), 11 to 20 is 2 calls ($0.02), and a full page of 100 is 10 calls ($0.10). A screen that matches nothing is free, and so is every error.
  • Every page is billed by its own rows, so paging does not change the price per company. Pages of 10 and one page of 100 cost the same for the same companies. A page that is not a multiple of 10 rounds up, so limit 1 costs $0.01 a company. Reading a whole result with cursors always costs at least one call for every 10 companies.
  • The cost of a request is in the X-Narwhal-Cost response header, in dollars with six decimals (a page of 23 companies shows 0.030000), and X-Narwhal-Balance is what is left. The answer itself has no cost field. Over MCP the same amount is taken from the balance and shown in the call log. A screen that matches nothing shows 0.000000.
  • A request is refused with 402 insufficient_credits before it runs when the balance is below one call, and after it ran when the balance cannot pay for the whole page. In both cases the companies are not delivered and nothing is charged. Send a smaller limit to pay less.
  • A screen takes up to 20 filters. The in operator takes 1 to 50 values. The operators each field accepts are on the filter list, and a filter that does not fit its field is 400 invalid_query with the reason. Text values are matched without regard to case.
  • limit is 25 unless you set it, and at most 100. Without order_by the companies come in company id order. order_by takes a numeric field, and order is desc unless you set asc.
  • A page can end with a next_cursor. Send it back as cursor with the same other parameters. A cursor from another query is 400 invalid_cursor.
  • fields names up to 106 numeric fields to return. Without it a row carries the fields you filtered or ordered on, or revenue, net income and total assets when there are none. Numbers are decimal strings, and a field the company has no value for is left out.
  • Where a later filing restated a figure, the screener shows the restated value, the same as the financials route.
  • as_of screens the companies as they stood on a past day, from 31 January 2010. Rows are kept for month ends, so a filing shows from the month end after it was made. Only companies that are listed today are covered, and a company whose newest figures end more than 18 months before the day is left out. The price fields cannot be used with as_of, and a day in the future is 400 invalid_query.
  • Line items take up to 10 tickers and up to 20 line_items, and limit is at most 40 periods for each company. A ticker that matches no company is listed in not_found and costs nothing, and a company named twice (AAPL and usa:AAPL) is found and billed once. Plan gates, held figures (figures that failed a plausibility check and are kept out of every answer) and withdrawn filings behave as on the financials route.

Endpoints

Each route is marked GET or POST. A POST route takes a JSON body, and its parameters below are the fields of that body. Every route needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.

Screen companies by their fundamentals

POST /v1/companies/screen

Find listed companies by their newest fiscal year across the filings registries: a list of filters on the fields from the filter list, an optional order and the fields to return. Paged with next_cursor. The price depends on the companies returned: one call for every 10, rounded up.

Each filter is an object with field, operator (gt, gte, lt, lte, eq, ne or in) and value. value is a number or text, a list for in, and a date as YYYY-MM-DD.

The price is one call for every 10 companies in the page, rounded up, and nothing for an empty page. See the limits above.

MCP: tool filings_screen_companies.

Parameters

ParameterWhereRequiredTypeMeaning
basisbodyNoone of annual, quarterly, ttmWhich row of each company to screen: annual: The newest fiscal year. Flows cover the year; balances are at its end.; quarterly: The newest quarter. Flows cover that quarter alone (a fourth quarter that is not filed on its own is the year minus the first three); balances are at its end. Growth is against the same quarter a year before. A company that files only annually has no quarterly row.; ttm: The last four quarters added up (the fiscal year itself for a company that files only annually or whose quarters are not four in a row); balances are at the end of the last quarter. Growth is against the four quarters ending a year before. Price ratios, where offered, use this basis whatever row is asked for.
filtersbodyNolist of objectThe conditions a company must meet, each {field, operator, value}. At most 20. Without filters every company matches.
currencybodyNostringOnly companies that report in this currency. Amounts are not converted, so a filter or order on an amount or per-share field needs one currency here or a currency eq filter.
fieldsbodyNolist of stringNumeric fields to return. Default: the ones filtered or ordered on.
order_bybodyNostringA numeric field. Default: company id.
orderbodyNoone of asc, descdesc puts the highest order_by value first, asc the lowest. Default desc.
langbodyNoone of en, originalen sends the English name of a company where one is known, original the name as filed. Default en.
as_ofbodyNodateScreen the companies as they stood on this day: each company's newest row built from filings made by then, from 2010-01-31 on. Rows are kept for month ends, so a filing shows from the month end after it was made (never earlier). Only companies that are listed today are covered, and a company whose newest figures end more than 18 months before the day is left out. The price fields (close, market_cap, the price ratios and yields) are not kept and cannot be used with it.
limitbodyNointegerCompanies on the page, 1 to 100. Default 25. A page is billed one call for every 10 companies, rounded up.
cursorbodyNostringnext_cursor of the previous page, with the same other parameters.

Response fields

FieldTypeSentMeaning
companieslist of objectAlwaysThe companies on this page, one row each. An empty list means nothing matched.
companies[].idstringAlwaysThe company id, for the other Filings API routes.
companies[].namestringAlwaysThe company name, in English where lang is en and one is known.
companies[].tickerstringOptionalThe ticker the company trades under, where it has one.
companies[].registryone of usa, jpn, kor, gbr, twn, aut, bel, cyp, cze, dnk, est, esp, fin, fra, grc, hrv, hun, isl, ita, ltu, lux, lva, mlt, nld, nor, pol, prt, rou, swe, svn, svkAlwaysThe registry the company files with.
companies[].countrystringOptionalThe company's country, an ISO 3166-1 alpha-3 code.
companies[].isicstringOptionalThe company's ISIC industry code.
companies[].currencystringOptionalThe currency the company reports in.
companies[].fiscal_yearintegerOptionalThe fiscal year of the row.
companies[].period_enddateOptionalThe last day of the period of the row.
companies[].filed_ondateOptionalThe day the filing the row comes from was made.
next_cursorstringOptionalSend it back as cursor to read the next page. Left out on the last page.
Request
curl -X POST -H "Authorization: Bearer $NARWHAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filters":[{"field":"net_margin","operator":"gt","value":20},{"field":"revenue","operator":"gt","value":50000000000}],"currency":"USD","order_by":"net_margin","fields":["net_margin","revenue"],"limit":3}' \
  "https://api.narwhalapi.com/v1/companies/screen"
Example response
{
  "companies": [
    {
      "id": "usa:0000723125",
      "name": "MICRON TECHNOLOGY INC",
      "ticker": "MU",
      "registry": "usa",
      "country": "USA",
      "isic": "2610",
      "currency": "USD",
      "fiscal_year": 2026,
      "period_end": "2026-09-03",
      "filed_on": "2026-10-09",
      "revenue": "133188000000",
      "net_margin": "63.7963"
    },
    {
      "id": "usa:0001045810",
      "name": "NVIDIA CORP",
      "ticker": "NVDA",
      "registry": "usa",
      "country": "USA",
      "isic": "2610",
      "currency": "USD",
      "fiscal_year": 2026,
      "period_end": "2026-01-25",
      "filed_on": "2026-02-25",
      "revenue": "215938000000",
      "net_margin": "55.6025"
    },
    {
      "id": "usa:0000789019",
      "name": "MICROSOFT CORP",
      "ticker": "MSFT",
      "registry": "usa",
      "country": "USA",
      "isic": "5820",
      "currency": "USD",
      "fiscal_year": 2026,
      "period_end": "2026-06-30",
      "filed_on": "2026-07-29",
      "revenue": "331839000000",
      "net_margin": "40.3054"
    }
  ],
  "next_cursor": "eyJpIjo3MjYsImtpbmQiOiJzY3JlZW4iLCJvIjoiNDAuMzA1NCIsInEiOiJlMWFjYzEzMjM1NTE5OGNmIiwidiI6MX0.z_-8qfS3wrPvM52pvfH2QEc6Z8LcktMIJH8zF5yjvmo"
}

List the screener's fields and limits

GET /v1/companies/screen/filters

Every field a screen can filter, order and return, with its type, unit and operators, the bases, the currencies and registries the screener holds, and its limits. Free: this route is not charged.

The answer is the same for every account. The currency and registry counts are those of the newest rebuild.

MCP: tool filings_get_screen_filters.

Parameters

This route takes no parameters.

Response fields

FieldTypeSentMeaning
fieldslist of objectAlways
fields[].fieldstringAlwaysThe field name, as used in filters, order_by and fields.
fields[].typeone of text, date, integer, amount, per_share, shares, percent, ratio, days, usdAlwaysThe kind of value the field holds.
fields[].operatorslist of one of gt, gte, lt, lte, eq, ne, inAlwaysThe operators a filter on this field accepts.
fields[].unitstringOptionalThe unit of the value, where it has one.
fields[].descriptionstringAlwaysWhat the field is.
baseslist of objectAlways
bases[].basisone of annual, quarterly, ttmAlwaysA value for basis.
bases[].descriptionstringAlwaysWhich row of each company it screens.
currencieslist of objectAlwaysCurrencies companies report in, with how many companies each.
currencies[].valuestringAlwaysA currency code.
currencies[].companiesintegerAlwaysHow many companies report in it.
registrieslist of objectAlways
registries[].valuestringAlwaysA registry code.
registries[].companiesintegerAlwaysHow many companies it holds.
built_atdate-timeOptionalWhen the screener table was last rebuilt.
max_filtersintegerOptionalThe most filters a screen takes.
max_limitintegerOptionalThe most companies a page holds.
Request
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/companies/screen/filters"
Example response
{
  "fields": [
    {
      "field": "registry",
      "type": "text",
      "operators": [
        "eq",
        "ne",
        "in"
      ],
      "description": "Registry that holds the company (usa, jpn, kor, ...)."
    },
    {
      "field": "revenue",
      "type": "amount",
      "operators": [
        "gt",
        "gte",
        "lt",
        "lte",
        "eq",
        "ne",
        "in"
      ],
      "unit": "currency",
      "description": "Revenue in `currency`, for the period of the row (see `basis`)."
    },
    {
      "field": "net_margin",
      "type": "percent",
      "operators": [
        "gt",
        "gte",
        "lt",
        "lte",
        "eq",
        "ne",
        "in"
      ],
      "unit": "percent",
      "description": "Net income over revenue (revenue above zero)."
    },
    {
      "field": "revenue_usd",
      "type": "usd",
      "operators": [
        "gt",
        "gte",
        "lt",
        "lte",
        "eq",
        "ne",
        "in"
      ],
      "unit": "USD",
      "description": "revenue in US dollars: the figure times `usd_rate_avg` (the period's average rate). Empty where there is no rate. Today the `_usd` figures are filled only for companies that report in US dollars, so a `_usd` filter returns only those companies."
    }
  ],
  "bases": [
    {
      "basis": "annual",
      "description": "The newest fiscal year. Flows cover the year; balances are at its end."
    },
    {
      "basis": "quarterly",
      "description": "The newest quarter. Flows cover that quarter alone (a fourth quarter that is not filed on its own is the year minus the first three); balances are at its end. Growth is against the same quarter a year before. A company that files only annually has no quarterly row."
    },
    {
      "basis": "ttm",
      "description": "The last four quarters added up (the fiscal year itself for a company that files only annually or whose quarters are not four in a row); balances are at the end of the last quarter. Growth is against the four quarters ending a year before. Price ratios, where offered, use this basis whatever row is asked for."
    }
  ],
  "currencies": [
    {
      "value": "USD",
      "companies": 5408
    },
    {
      "value": "JPY",
      "companies": 3804
    },
    {
      "value": "KRW",
      "companies": 2628
    }
  ],
  "registries": [
    {
      "value": "usa",
      "companies": 5520
    },
    {
      "value": "jpn",
      "companies": 3784
    },
    {
      "value": "kor",
      "companies": 2637
    }
  ],
  "built_at": "2026-11-16T04:18:58.438922Z",
  "max_filters": 20,
  "max_limit": 100
}

Get chosen line items for up to 10 companies

POST /v1/companies/line-items

Chosen financial line items for up to 10 tickers in one request: the periods of each company, newest first. Tickers that match no company are listed in not_found. One call for each company found.

period is annual unless you set it. The answer has the rows of the period you asked for under that name, newest first, and ttm rows under ttm.

The price is one call for each company found, at most 10. A request that finds none is free.

MCP: tool filings_search_line_items.

Parameters

ParameterWhereRequiredTypeMeaning
tickersbodyYeslist of stringCompany ids (usa:0000320193), registry tickers (usa:AAPL, jpn:7203) or bare US tickers (AAPL).
line_itemsbodyYeslist of stringStandard item names, as fields of the financials route.
periodbodyNoone of annual, semiannual, quarterly, ttmttm is the last four quarters added up at each quarter end (balance-sheet items are those of the last quarter; a company that files only annually gets its fiscal years). The others are as on the financials route.
start_datebodyNodateOnly periods ending on or after this day.
end_datebodyNodateOnly periods ending on or before this day.
limitbodyNointegerPeriods per company, newest first. Default: 1, or every period in the date range (at most 40) when a date is given.

Response fields

FieldTypeSentMeaning
resultslist of objectAlways
results[].idstringAlwaysThe company id.
results[].currencystringOptionalThe currency of the figures.
results[].basisone of consolidated, standaloneOptionalWhether the figures are consolidated or standalone.
results[].from_fyintegerOptionalThe first fiscal year the rows go back to.
results[].annuallist of objectOptionalThe annual rows, newest first. Sent when period is annual.
results[].annual[].fyintegerAlwaysThe fiscal year of the row.
results[].annual[].fqintegerOptionalThe fiscal quarter, for a quarterly row.
results[].annual[].fhintegerOptionalThe fiscal half, for a half year row.
results[].annual[].enddateAlwaysThe last day of the period.
results[].annual[].formstringOptionalThe form of the filing that supplies most of the values the row shows, such as 10-K. The most recently filed wins a tie. Only the fields you asked for are counted, so form can differ between two requests with different line_items.
results[].annual[].currencystringOptionalCurrency of the prices.
results[].annual[].derivedlist of stringOptionalThe items of the row that Narwhal worked out rather than took from the filing.
results[].semiannuallist of objectOptionalThe half year rows, newest first. Sent when period is semiannual.
results[].semiannual[].fyintegerAlwaysThe fiscal year of the row.
results[].semiannual[].fqintegerOptionalThe fiscal quarter, for a quarterly row.
results[].semiannual[].fhintegerOptionalThe fiscal half, for a half year row.
results[].semiannual[].enddateAlwaysThe last day of the period.
results[].semiannual[].formstringOptionalThe form of the filing that supplies most of the values the row shows, such as 10-K. The most recently filed wins a tie. Only the fields you asked for are counted, so form can differ between two requests with different line_items.
results[].semiannual[].currencystringOptionalCurrency of the prices.
results[].semiannual[].derivedlist of stringOptionalThe items of the row that Narwhal worked out rather than took from the filing.
results[].quarterlylist of objectOptionalThe quarterly rows, newest first. Sent when period is quarterly.
results[].quarterly[].fyintegerAlwaysThe fiscal year of the row.
results[].quarterly[].fqintegerOptionalThe fiscal quarter, for a quarterly row.
results[].quarterly[].fhintegerOptionalThe fiscal half, for a half year row.
results[].quarterly[].enddateAlwaysThe last day of the period.
results[].quarterly[].formstringOptionalThe form of the filing that supplies most of the values the row shows, such as 10-K. The most recently filed wins a tie. Only the fields you asked for are counted, so form can differ between two requests with different line_items.
results[].quarterly[].currencystringOptionalCurrency of the prices.
results[].quarterly[].derivedlist of stringOptionalThe items of the row that Narwhal worked out rather than took from the filing.
results[].as_ofdateOptionalThe day the figures are as of, where the period asks for one.
results[].ttmlist of objectOptionalThe trailing four quarter rows, newest first. Sent when period is ttm.
results[].ttm[].fyintegerAlwaysThe fiscal year of the row.
results[].ttm[].fqintegerOptionalThe fiscal quarter, for a quarterly row.
results[].ttm[].fhintegerOptionalThe fiscal half, for a half year row.
results[].ttm[].enddateAlwaysThe last day of the period.
results[].ttm[].formstringOptionalThe form of the filing that supplies most of the values the row shows, such as 10-K. The most recently filed wins a tie. Only the fields you asked for are counted, so form can differ between two requests with different line_items.
results[].ttm[].currencystringOptionalCurrency of the prices.
results[].ttm[].derivedlist of stringOptionalThe items of the row that Narwhal worked out rather than took from the filing.
not_foundlist of stringOptionalTickers or ids that match no company.
Request
curl -X POST -H "Authorization: Bearer $NARWHAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"tickers":["AAPL","MSFT"],"line_items":["revenue","net_income"],"limit":1}' \
  "https://api.narwhalapi.com/v1/companies/line-items"
Example response
{
  "results": [
    {
      "id": "usa:0000320193",
      "currency": "USD",
      "annual": [
        {
          "fy": 2026,
          "end": "2026-09-26",
          "form": "10-K",
          "derived": [],
          "revenue": "478834000000",
          "net_income": "132175000000"
        }
      ],
      "as_of": "2026-11-03"
    },
    {
      "id": "usa:0000789019",
      "currency": "USD",
      "annual": [
        {
          "fy": 2026,
          "end": "2026-06-30",
          "form": "10-K",
          "derived": [],
          "revenue": "331839000000",
          "net_income": "133749000000"
        }
      ],
      "as_of": "2026-07-29"
    }
  ],
  "not_found": []
}

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.
invalid_cursor400The cursor is not one this request returned, or it comes from a different request.
insufficient_credits402Your credit balance is less than the request costs.
screener_unavailable503The nightly screener table has not been built yet. Try again later. This is not charged.
company_data_unavailable503An `as_of` screen could not be read in time. Try again shortly. This is not charged.

Was this page helpful?