FL
FundLens

API Reference

REST API for SEC EDGAR fund holdings and exposures. Base URL https://api.fundlens.io/v1.

Authentication

All requests require an API key, sent as the x-api-key header. Get one from your dashboard.

curl https://api.fundlens.io/v1/funds \
  -H "x-api-key: your_api_key"

Conventions

Datesstring
All dates are YYYY-MM-DD, interpreted as UTC.
Monetary valuesinteger
valueUsd and assetsUnderManagement are in US dollars.
Point-in-time
Holdings/exposures carry both asOfDate (portfolio snapshot date) and filingDate (when the SEC made it public). Use available_as_of for lookahead-safe queries.
Source
Holdings come from SEC EDGAR Form N-PORT (structured data available from ~2019 onward).
Errors
Standard HTTP status codes. 402 means the request needs a subscription plan (Starter or Growth) — e.g. historical / point-in-time queries on a Free or Pay-As-You-Go key.
GET/funds

List Funds

Get a paginated list of all available funds with basic metadata.

Query parameters

limitinteger
Number of results (default 20, max 100).
offsetinteger
Pagination offset (default 0).

Response fields

fundsFund[]
Array of fund objects.
paginationobject
Pagination metadata.
Fund object
tickerstring | null
Primary exchange ticker (e.g. "VTI"). Null if not mapped.
namestring
Fund name.
cikstring
SEC Central Index Key of the filing entity (10 digits, zero-padded).
seriesIdstring | null
SEC series identifier. Trust-level filers without a series use a synthetic "CIK_<cik>".
assetsUnderManagementnumber | null
Total net assets, in US dollars.
holdingsCountinteger | null
Number of holdings in the latest filing.
lastFilingDatestring | null
Date of the most recent filing (YYYY-MM-DD).
dataAsOfstring | null
Portfolio as-of date of the latest filing (YYYY-MM-DD).
pagination
limitinteger
Page size used for this response.
offsetinteger
Offset used for this response.
totalinteger
Total number of records available.
Request
curl "https://api.fundlens.io/v1/funds?limit=20&offset=0" \
  -H "x-api-key: your_api_key"
Response
{
  "funds": [
    {
      "ticker": "VTI",
      "name": "Vanguard Total Stock Market ETF",
      "cik": "0000036405",
      "seriesId": "S000002848",
      "assetsUnderManagement": 1234567890000,
      "holdingsCount": 503,
      "lastFilingDate": "2024-10-28",
      "dataAsOf": "2024-09-30"
    }
  ],
  "pagination": { "total": 5000, "limit": 20, "offset": 0 }
}
GET/funds/:ticker

Get Fund Details

Get metadata for a specific fund by ticker.

Response fields

tickerstring | null
Primary exchange ticker (e.g. "VTI"). Null if not mapped.
namestring
Fund name.
cikstring
SEC Central Index Key of the filing entity (10 digits, zero-padded).
seriesIdstring | null
SEC series identifier. Trust-level filers without a series use a synthetic "CIK_<cik>".
assetsUnderManagementnumber | null
Total net assets, in US dollars.
holdingsCountinteger | null
Number of holdings in the latest filing.
lastFilingDatestring | null
Date of the most recent filing (YYYY-MM-DD).
dataAsOfstring | null
Portfolio as-of date of the latest filing (YYYY-MM-DD).
Request
curl https://api.fundlens.io/v1/funds/VTI \
  -H "x-api-key: your_api_key"
Response
{
  "ticker": "VTI",
  "name": "Vanguard Total Stock Market ETF",
  "cik": "0000036405",
  "seriesId": "S000002848",
  "assetsUnderManagement": 1234567890000,
  "holdingsCount": 503,
  "lastFilingDate": "2024-10-28",
  "dataAsOf": "2024-09-30"
}
GET/funds/:ticker/holdings

Get Holdings

Get portfolio holdings for a fund's latest filing, or for a point-in-time date. Paginated.

Query parameters

limitinteger
Number of holdings (default 100, max 500).
offsetinteger
Pagination offset (default 0).
as_ofdatesubscription
Point-in-time date (YYYY-MM-DD). Returns the most recent filing whose portfolio date (asOfDate) is on or before this date.
available_as_ofdatesubscription
Lookahead-safe date (YYYY-MM-DD). Returns the most recent filing already published (SEC-accepted) on or before this date — what was knowable then. Combinable with as_of.

Response fields

fundTickerstring
The requested fund ticker.
fundIdentifierstring
Stable fund identifier (seriesId, or CIK for trust-level filers).
asOfDatestring
Portfolio snapshot date of the returned filing (N-PORT period of report).
filingDatestring
Always on or after asOfDate (a filing is accepted after the period it covers). Gate historical decisions on this to avoid lookahead.
accessionNumberstring
SEC accession number of the source filing (provenance).
totalHoldingsinteger
Total holdings in this filing (independent of pagination).
totalAssetsUsdnumber | null
Fund-level gross total assets for this snapshot (N-PORT Item totAssets), in US dollars. This is gross assets — not net assets, and only an approximation of AUM. NAV per share and shares outstanding are not in N-PORT.
currencystring
Reporting currency of the monetary fields (e.g. "USD").
holdingsHolding[]
Array of holding objects.
paginationobject
Pagination metadata.
sourcestring
Data source, e.g. "SEC EDGAR N-PORT".
Holding object (holdings[])
namestring
Security name as reported in the filing.
cusipstring | null
9-character CUSIP identifier.
isinstring | null
ISIN identifier, when available.
figistring | null
OpenFIGI composite FIGI (exchange-independent identity), when available.
tickerstring | null
Resolved exchange ticker for the security, when available.
valueUsdnumber
Market value of the position, in US dollars.
sharesinteger | null
Number of shares / units held.
weightPercentnumber
Position weight as a percent of the portfolio (7.21 = 7.21%).
securityTypestring
Asset class: equity, bond, cash, or other.
sectorstring | null
Sector classification.
industrystring | null
Industry classification.
countrystring | null
Country of the security.
Request
curl "https://api.fundlens.io/v1/funds/VTI/holdings?limit=10&as_of=2024-09-30" \
  -H "x-api-key: your_api_key"
Response
{
  "fundTicker": "VTI",
  "fundIdentifier": "S000002848",
  "asOfDate": "2024-09-30",
  "filingDate": "2024-10-28",
  "accessionNumber": "0001752724-24-241234",
  "totalHoldings": 503,
  "totalAssetsUsd": 450000000000,
  "currency": "USD",
  "holdings": [
    {
      "name": "Apple Inc",
      "cusip": "037833100",
      "isin": "US0378331005",
      "figi": "BBG000B9XRY4",
      "ticker": "AAPL",
      "valueUsd": 89000000000,
      "shares": 394000000,
      "weightPercent": 7.21,
      "securityType": "equity",
      "sector": "technology",
      "industry": "hardware",
      "country": "US"
    }
  ],
  "pagination": { "limit": 10, "offset": 0, "total": 503 },
  "source": "SEC EDGAR N-PORT"
}
GET/funds/:ticker/holdings/historySubscription

List Available Filings

List every available point-in-time filing for a fund. Enumerate snapshots, then pull each via the holdings endpoint.

Response fields

fundTickerstring
The requested fund ticker.
fundIdentifierstring
Stable fund identifier (seriesId, or CIK for trust-level filers).
filingsFiling[]
Available filings, most recent first.
sourcestring
Data source.
Filing object (filings[])
asOfDatestring
Portfolio snapshot date (YYYY-MM-DD).
filingDatestring
Always on or after asOfDate (a filing is accepted after the period it covers). Gate historical decisions on this to avoid lookahead.
accessionNumberstring
SEC accession number.
totalHoldingsinteger
Number of holdings in this filing.
totalAssetsUsdnumber | null
Gross total assets for this snapshot (N-PORT totAssets), in US dollars.
Request
curl "https://api.fundlens.io/v1/funds/VTI/holdings/history" \
  -H "x-api-key: your_api_key"
Response
{
  "fundTicker": "VTI",
  "fundIdentifier": "S000002848",
  "filings": [
    { "asOfDate": "2024-09-30", "filingDate": "2024-10-28", "accessionNumber": "0001752724-24-241234", "totalHoldings": 503, "totalAssetsUsd": 450000000000 },
    { "asOfDate": "2024-06-30", "filingDate": "2024-07-29", "accessionNumber": "0001752724-24-176543", "totalHoldings": 501, "totalAssetsUsd": 442000000000 }
  ],
  "source": "SEC EDGAR N-PORT"
}
GET/funds/:ticker/exposures

Get Exposures

Aggregated sector, industry, security-type, and country exposure for a fund, computed from its holdings.

Query parameters

as_ofdatesubscription
Point-in-time date (YYYY-MM-DD), on-or-before semantics.
available_as_ofdatepaid
Lookahead-safe date (YYYY-MM-DD).

Response fields

fundTickerstring
The requested fund ticker.
asOfDatestring
Portfolio snapshot date of the source filing.
filingDatestring
Always on or after asOfDate (a filing is accepted after the period it covers). Gate historical decisions on this to avoid lookahead.
exposuresobject
Breakdowns by sector, industry, securityType, and country.
sourcestring
Data source.
exposures.sector / .industry / .securityType / .country — each an array of:
namestring
The category name (e.g. "technology", "US").
weightPercentnumber
Aggregate portfolio weight for that category (percent).
Request
curl https://api.fundlens.io/v1/funds/VTI/exposures \
  -H "x-api-key: your_api_key"
Response
{
  "fundTicker": "VTI",
  "asOfDate": "2024-09-30",
  "filingDate": "2024-10-28",
  "exposures": {
    "sector": [
      { "name": "technology", "weightPercent": 32.5 },
      { "name": "healthcare", "weightPercent": 12.1 }
    ],
    "industry": [{ "name": "semiconductors", "weightPercent": 8.2 }],
    "securityType": [{ "name": "equity", "weightPercent": 99.2 }],
    "country": [{ "name": "US", "weightPercent": 96.8 }]
  },
  "source": "SEC EDGAR N-PORT"
}
Growth plan

Bulk export

For backtesting and bulk loading, we provide the full historical holdings dataset as a point-in-time-safe file export rather than thousands of paginated calls. Available on the Growth plan — email sales@fundlens.io with the tickers and window you need.

What you get

Layout
A partitioned dataset, one CSV per fund (fundTicker=SPY/holdings.csv). Parquet on request.
Rows
One row per holding per snapshot. Fund- and snapshot-level fields (asOfDate, filingDate, totalAssetsUsd) are denormalized onto every row.
Columns
Same fields as the holdings endpoint, plus fundTicker, fundIdentifier, accessionNumber, totalAssetsUsd, and currency.
Units
valueUsd and totalAssetsUsd are in US dollars — no cents, no division to apply.
manifest.json
Per fund: row count, snapshot count, min/max asOfDate, min/max filingDate, file SHA256, and byte size.
DATA_DICTIONARY.md
Column semantics, units, and the point-in-time lineage answers (see right).

Point-in-time lineage

filingDate
Always the SEC public acceptance date, always on or after asOfDate. Gate decisions on it.
available_as_of
Selects the latest filing where filingDate ≤ date. Every export row keeps filingDate so you can reproduce the gate offline.
Amendments
NPORT-P/A amendments are separate snapshots with their own accessionNumber and filingDate.
fundIdentifier
Stable across ticker / share-class changes (seriesId, or CIK for trust-level filers).
shares
Exactly as reported in the filing — not split-adjusted or normalized.
totalAssetsUsd
N-PORT gross total assets — not net assets, and not a flow series. NAV / shares outstanding are not in N-PORT.
Export layout
manifest.json
DATA_DICTIONARY.md
fundTicker=SPY/holdings.csv
fundTicker=QQQ/holdings.csv
fundTicker=VTI/holdings.csv
...

# holdings.csv columns
fundTicker,fundIdentifier,asOfDate,filingDate,
accessionNumber,source,totalHoldings,
totalAssetsUsd,currency,ticker,name,cusip,
isin,figi,shares,valueUsd,weightPercent,
securityType,sector,industry,country