How do you ask for one number without downloading everything?

You want Apple's market capitalisation. One number. Without a filter, /fundamentals/AAPL.US hands you the company description, a list of officers with birth years, every cross-listing, institutional and fund holder tables, an insider-transaction array, ESG scores, quarterly and annual outstanding share counts, an earnings history, and three financial statements at two periodicities across every reporting date on file. Then you take one field out of it and throw the rest away.

Do that across 500 tickers on a schedule and you have built an expensive, slow, fragile pipeline for no reason.

The filter parameter

filter takes a path into the response, with :: as the separator. It accepts these sections: General, Highlights, Valuation, SharesStats, Technicals, SplitsDividends, AnalystRatings, Holders, InsiderTransactions, ESGScores, outstandingShares, Earnings, and Financials. Omit it and you get all of them.

It nests as deep as the data does:

• filter=Highlights — one section.
• filter=Highlights::MarketCapitalization — one scalar.
• filter=Financials::Income_Statement::yearly — one statement, one periodicity. The key is yearly, not annual: ::annual answers 200 and the string "NA" (checked 28 September 2026).
• filter=Financials::Balance_Sheet::quarterly::2024-06-30 — one statement on one date.

The last form is the one that changes how you work. A quarterly balance sheet for one date is a small object. The unfiltered response containing it is not.

A sense of what you are skipping

Apple's SplitsDividends.NumberDividendsByYear alone carries 24 year entries, running 1987 to 1995 and then 2012 to 2026 — the gap is real, because Apple paid no dividend between those runs. That is one sub-object inside one section. Financials holds three statements, each with a yearly and a quarterly object keyed by reporting date, each entry a full line-item set for that date. Holders holds two tables of institutions and funds.

None of that is waste when you want it. All of it is waste when you wanted PERatio.

The other three parameters

• historical — 0 or 1. Set to 1 to get historical data for the sections that have a historical form, outstandingShares being the documented example.
• from / to — YYYY-MM-DD, to bound that historical window.
• no_cache — 0 or 1. Set to 1 to bypass the cache. Useful when you are chasing a value you believe has just changed; wasteful as a default, because you give up the cache on every call.
• version — selects the response format. There is also a parallel path, /v1.1/fundamentals/{ticker}, whose documented difference from v1 is in the Earnings Trend section: v1.1 splits it into Quarterly and Annual sub-objects and adds a quarter field to the quarterly items. If you pin a version, write down which and why, or a future schema change will look like a data change.

The habit worth forming

Fetch narrow by default, wide on purpose. Two concrete consequences: your job finishes faster because there is less to transfer and parse, and your failures get more legible — a filtered call that returns nothing tells you precisely which section is unavailable for that instrument, where an unfiltered call buries the same fact under everything that did arrive.

One caution. filter changes the shape of the response as well as its size: filter=Highlights::MarketCapitalization does not return a nested object with one key, it returns the value. Write the parser against what the filtered call actually returns, not against a mental model of the full document.

Try it now

1. /fundamentals/AAPL.US unfiltered returned 969,500 bytes on 28 September 2026; with filter=Highlights::MarketCapitalization it returned 13, the bare number 4977636933632. Compute the ratio of the two lengths. That ratio is your saving on every future call. The table below is a middle road, filter=Highlights, reduced to five of its fields.

2. Below is filter=Financials::Balance_Sheet::quarterly for Apple, reduced to the two newest and two oldest dates. The response has one entry per quarter end between them. Count the dates from the oldest to the newest. That count is how much history you would have re-downloaded on every run without the filter.

3. /fundamentals/SPY.US?filter=Financials, an ETF, returned status 200 and the whole body below on 28 September 2026: a JSON string, not an object and not an error.

"NA"

Connect it to the previous lesson: shape follows instrument type, and the filter cannot conjure a section that does not exist. Then say what your parser does when a filtered call hands it a string.