A point-in-time float series for US stocks is not something the Massive float endpoint, /stocks/vX/float, can give you, and the request that looks as if it should does not fail. Add a date to the request and the endpoint ignores it and returns the latest record, so a backtest that asks for the float on a past date gets today's value without any error.
Applies to
- Plans: every Stocks plan, including the free Basic plan, per the Float documentation.
- Endpoints: /stocks/vX/float.
- Asset classes: US stocks.
How to read the latest float
curl -X GET "https://api.massive.com/stocks/vX/float?ticker=BRK.B&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{
"ticker": "BRK.B",
"free_float": 1387477847,
"effective_date": "2026-09-23",
"free_float_percent": 98.5
}
]
}
effective_date is the effective date of that float measurement, and it is the only date on the record: there is no separate field for when the value was last checked. The date differs from ticker to ticker. Once a newer measurement replaces this one, your response shows the newer date and value.
What a past date returns
A past date on the Massive float endpoint returns the same latest record, because the endpoint has no date parameter and ignores a parameter it does not recognize:
curl -X GET "https://api.massive.com/stocks/vX/float?ticker=BRK.B&date=2020-01-02&apiKey=YOUR_API_KEY"
Response
{
"status": "OK",
"results": [
{
"ticker": "BRK.B",
"free_float": 1387477847,
"effective_date": "2026-09-23",
"free_float_percent": 98.5
}
]
}
The request for 2 January 2020 returns the measurement effective on 23 September 2026. Filters on effective_date, such as effective_date.lte, are ignored the same way. Read effective_date on every response: when it is later than the date you wanted, the value is not a historical one.
How to build a float history yourself
A float history from Massive has to be collected going forward, because the float endpoint keeps no earlier values:
- Request the whole set on a schedule, such as daily, with /stocks/vX/float?limit=5000, and follow next_url until it is absent.
- Store each record keyed on ticker and effective_date.
- When a ticker's effective_date changes, add a row rather than overwriting the old one.
A history built this way starts on the day you begin collecting. Earlier measurements are not available from Massive.
Free float is not shares outstanding
Free float on Massive is a narrower count than shares outstanding. The Float documentation excludes shares held by founders, officers and directors, controlling shareholders, employee plans, restricted or locked-up holdings and any shareholder owning 5% or more, among others. Share counts and market cap come from the ticker details endpoint, which the articles under Related explain.
Why this happens
Massive's float dataset holds one record per ticker, the latest measurement, which is what the documentation describes: "Retrieve the latest free float for a specified stock ticker." A new measurement replaces the previous one rather than being added beside it. The documentation also notes that float figures "may reflect ownership changes with a reporting lag, since they are based on publicly available disclosures and ownership information rather than real-time trading activity."
If you see an error
An empty results array with HTTP 200 means there is no float record for that ticker.
A record whose effective_date is later than the date you asked for is the latest record. The date parameter was ignored, not applied.
sort accepts only ticker and effective_date. Any other column returns HTTP 400 with Invalid query parameter: 'sort'. Expected one of [ticker, effective_date], followed by the value you sent.
