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_ 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 _, for example revenue_, which needs no currency. Today the _ figures are filled only for companies that report in US dollars, so a _ 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:/. 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
| What | Every account |
|---|---|
| Screen | Included. One call for every 10 companies returned, rounded up |
| Filter list | Included. Free |
| Line items | Included. 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
limit1 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-Costresponse header, in dollars with six decimals (a page of 23 companies shows0.030000), andX-Narwhal-Balanceis 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 shows0.000000. - A request is refused with 402
insufficient_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 smallercredits limitto pay less. - A screen takes up to 20 filters. The
inoperator 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 400invalid_with the reason. Text values are matched without regard to case.query limitis 25 unless you set it, and at most 100. Withoutorder_the companies come in company id order.by order_takes a numeric field, andby orderisdescunless you setasc.- A page can end with a
next_. Send it back ascursor cursorwith the same other parameters. A cursor from another query is 400invalid_.cursor fieldsnames 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_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 withof as_, and a day in the future is 400of invalid_.query - Line items take up to 10
tickersand up to 20line_, anditems limitis at most 40 periods for each company. A ticker that matches no company is listed innot_and costs nothing, and a company named twice (found AAPLandusa: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_. 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_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
basis | body | No | one of annual, quarterly, ttm | Which 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. |
filters | body | No | list of object | The conditions a company must meet, each {field, operator, value}. At most 20. Without filters every company matches. |
currency | body | No | string | Only 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. |
fields | body | No | list of string | Numeric fields to return. Default: the ones filtered or ordered on. |
order_ | body | No | string | A numeric field. Default: company id. |
order | body | No | one of asc, desc | desc puts the highest order_ value first, asc the lowest. Default desc. |
lang | body | No | one of en, original | en sends the English name of a company where one is known, original the name as filed. Default en. |
as_ | body | No | date | Screen 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_, the price ratios and yields) are not kept and cannot be used with it. |
limit | body | No | integer | Companies on the page, 1 to 100. Default 25. A page is billed one call for every 10 companies, rounded up. |
cursor | body | No | string | next_ of the previous page, with the same other parameters. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
companies | list of object | Always | The companies on this page, one row each. An empty list means nothing matched. |
companies[].id | string | Always | The company id, for the other Filings API routes. |
companies[].name | string | Always | The company name, in English where lang is en and one is known. |
companies[].ticker | string | Optional | The ticker the company trades under, where it has one. |
companies[].registry | one 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, svk | Always | The registry the company files with. |
companies[].country | string | Optional | The company's country, an ISO 3166-1 alpha-3 code. |
companies[].isic | string | Optional | The company's ISIC industry code. |
companies[].currency | string | Optional | The currency the company reports in. |
companies[].fiscal_ | integer | Optional | The fiscal year of the row. |
companies[].period_ | date | Optional | The last day of the period of the row. |
companies[].filed_ | date | Optional | The day the filing the row comes from was made. |
next_ | string | Optional | Send it back as cursor to read the next page. Left out on the last page. |
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"{
"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_.
Parameters
This route takes no parameters.
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
fields | list of object | Always | |
fields[].field | string | Always | The field name, as used in filters, order_ and fields. |
fields[].type | one of text, date, integer, amount, per_share, shares, percent, ratio, days, usd | Always | The kind of value the field holds. |
fields[].operators | list of one of gt, gte, lt, lte, eq, ne, in | Always | The operators a filter on this field accepts. |
fields[].unit | string | Optional | The unit of the value, where it has one. |
fields[].description | string | Always | What the field is. |
bases | list of object | Always | |
bases[].basis | one of annual, quarterly, ttm | Always | A value for basis. |
bases[].description | string | Always | Which row of each company it screens. |
currencies | list of object | Always | Currencies companies report in, with how many companies each. |
currencies[].value | string | Always | A currency code. |
currencies[].companies | integer | Always | How many companies report in it. |
registries | list of object | Always | |
registries[].value | string | Always | A registry code. |
registries[].companies | integer | Always | How many companies it holds. |
built_ | date-time | Optional | When the screener table was last rebuilt. |
max_ | integer | Optional | The most filters a screen takes. |
max_ | integer | Optional | The most companies a page holds. |
curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
"https://api.narwhalapi.com/v1/companies/screen/filters"{
"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_. 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_.
Parameters
| Parameter | Where | Required | Type | Meaning |
|---|---|---|---|---|
tickers | body | Yes | list of string | Company ids (usa:0000320193), registry tickers (usa:AAPL, jpn:7203) or bare US tickers (AAPL). |
line_ | body | Yes | list of string | Standard item names, as fields of the financials route. |
period | body | No | one of annual, semiannual, quarterly, ttm | ttm 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_ | body | No | date | Only periods ending on or after this day. |
end_ | body | No | date | Only periods ending on or before this day. |
limit | body | No | integer | Periods per company, newest first. Default: 1, or every period in the date range (at most 40) when a date is given. |
Response fields
| Field | Type | Sent | Meaning |
|---|---|---|---|
results | list of object | Always | |
results[].id | string | Always | The company id. |
results[].currency | string | Optional | The currency of the figures. |
results[].basis | one of consolidated, standalone | Optional | Whether the figures are consolidated or standalone. |
results[].from_ | integer | Optional | The first fiscal year the rows go back to. |
results[].annual | list of object | Optional | The annual rows, newest first. Sent when period is annual. |
results[].annual[].fy | integer | Always | The fiscal year of the row. |
results[].annual[].fq | integer | Optional | The fiscal quarter, for a quarterly row. |
results[].annual[].fh | integer | Optional | The fiscal half, for a half year row. |
results[].annual[].end | date | Always | The last day of the period. |
results[].annual[].form | string | Optional | The 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_. |
results[].annual[].currency | string | Optional | Currency of the prices. |
results[].annual[].derived | list of string | Optional | The items of the row that Narwhal worked out rather than took from the filing. |
results[].semiannual | list of object | Optional | The half year rows, newest first. Sent when period is semiannual. |
results[].semiannual[].fy | integer | Always | The fiscal year of the row. |
results[].semiannual[].fq | integer | Optional | The fiscal quarter, for a quarterly row. |
results[].semiannual[].fh | integer | Optional | The fiscal half, for a half year row. |
results[].semiannual[].end | date | Always | The last day of the period. |
results[].semiannual[].form | string | Optional | The 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_. |
results[].semiannual[].currency | string | Optional | Currency of the prices. |
results[].semiannual[].derived | list of string | Optional | The items of the row that Narwhal worked out rather than took from the filing. |
results[].quarterly | list of object | Optional | The quarterly rows, newest first. Sent when period is quarterly. |
results[].quarterly[].fy | integer | Always | The fiscal year of the row. |
results[].quarterly[].fq | integer | Optional | The fiscal quarter, for a quarterly row. |
results[].quarterly[].fh | integer | Optional | The fiscal half, for a half year row. |
results[].quarterly[].end | date | Always | The last day of the period. |
results[].quarterly[].form | string | Optional | The 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_. |
results[].quarterly[].currency | string | Optional | Currency of the prices. |
results[].quarterly[].derived | list of string | Optional | The items of the row that Narwhal worked out rather than took from the filing. |
results[].as_ | date | Optional | The day the figures are as of, where the period asks for one. |
results[].ttm | list of object | Optional | The trailing four quarter rows, newest first. Sent when period is ttm. |
results[].ttm[].fy | integer | Always | The fiscal year of the row. |
results[].ttm[].fq | integer | Optional | The fiscal quarter, for a quarterly row. |
results[].ttm[].fh | integer | Optional | The fiscal half, for a half year row. |
results[].ttm[].end | date | Always | The last day of the period. |
results[].ttm[].form | string | Optional | The 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_. |
results[].ttm[].currency | string | Optional | Currency of the prices. |
results[].ttm[].derived | list of string | Optional | The items of the row that Narwhal worked out rather than took from the filing. |
not_ | list of string | Optional | Tickers or ids that match no company. |
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"{
"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_. 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. |
invalid_ | 400 | The cursor is not one this request returned, or it comes from a different request. |
insufficient_ | 402 | Your credit balance is less than the request costs. |
screener_ | 503 | The nightly screener table has not been built yet. Try again later. This is not charged. |
company_ | 503 | An `as_of` screen could not be read in time. Try again shortly. This is not charged. |
Was this page helpful?