API reference

ETF holdings API

Current and historical holdings, availability checks, and full portfolio reports.

ContentsOverview

Authentication

Bearer authentication

All v1 endpoints require an API key in the Authorization header.

HeaderAuthorization: Bearer $ETF_HOLDINGS_API_KEY

Base URLhttps://etf-holdings.com/api/v1

Access

Holdings endpoints and reports are billable; coverage checks are not.

Errors

Error responses

Errors use a consistent JSON envelope. Include requestId when contacting support.

400Invalid or missing request parameters.

401Missing, malformed, or revoked API key.

402Account access or available balance cannot cover the request.

429Request rate exceeded; retry with backoff.

503No supported holdings or report snapshot was available for the request.

{
  "error": {
    "code": "holdings_unavailable",
    "message": "Holdings are not available for that request",
    "requestId": "req_123"
  }
}

Coverage

Coverage checker

Check current and historical availability for a ticker.

CurrentWaiting

Check current endpoint coverage

Check current endpoint coverage.

HistoricalWaiting

Check historical endpoint coverage

Check supported historical years.

Current

Current holdings

Issuer-provided snapshots and current availability.

Current source integrationsView supported issuer families

Availability varies by fund and date. Check coverage before requesting a snapshot.

Aberdeen...
AdvisorShares...
Alger...
ALPS...
American Century...
Amplify...
ARK...
Avantis...
Bitwise...
BNY Mellon...
Calamos...
Capital Group...
Davis...
Dimensional...
Eaton Vance...
Fidelity...
First Trust...
Global X...
GMO...
Goldman Sachs...
GraniteShares...
Grayscale...
Harbor...
Innovator...
Invesco...
iShares...
JPMorgan...
MarketDesk...
MicroSectors...
Neuberger...
ProShares...
Roundhill...
Schwab...
SEI...
Simplify...
Sprott...
State Street...
Strive...
T. Rowe Price...
USCF...
VanEck...
Vanguard...
WisdomTree...

Current holdings

Get the latest available holdings

Resolve an issuer-published holdings snapshot for an ETF. Use at to request the latest cached snapshot on or before a date.

GET/api/v1/current/holdings

API key requiredIssuer-backedBillable: per returned holding

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	ETF or fund ticker symbol.`SPY`
`at`Optional	`ISO 8601 date`	Optional query time. The endpoint resolves the latest snapshot on or before it.`2026-06-01`
`limit`Optional	`integer`	Maximum holdings to return after descending-weight sorting.`25`
`fallback`Optional	`boolean`	When true, fall back to the latest SEC filing-backed holdings if issuer holdings are unavailable. Defaults to false.`false`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/current/holdings?ticker=SPY&limit=25' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`ticker`	`string`	The ETF ticker that was resolved for this request.
`asOf`	`date`	The snapshot date that was returned.
`source`Optional	`string`	A source label when the resolved snapshot has one.
`holdings[]`	`Holding[]`	Holdings sorted by descending weight. The optional limit is applied after sorting.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/current/holdings" \
  --get \
  --data-urlencode "ticker=SPY" \
  --data-urlencode "limit=25" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Current coverage

Check current data availability

Check whether an issuer-backed current holdings snapshot is available for a ticker, without retrieving its holdings table.

GET/api/v1/current/coverage

API key requiredAvailability onlyCurrent source

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	ETF or fund ticker symbol to check.`SPY`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/current/coverage?ticker=SPY' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`lookup`	`CoverageLookup`	Coverage state and the metadata available for the requested data family.
`lookup.status`	`string`	Current lookups use fresh, cached, stale, or missing. Historical lookups can use mapped, mixed, legacy_only, missing, or scanning.
`lookup.asOf`Optional	`date`	The latest available snapshot date for a current lookup.
`lookup.yearCoverage`Optional	`object`	Historical-year availability and per-year report details for a historical lookup.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/current/coverage" \
  --get \
  --data-urlencode "ticker=SPY" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Historical

Historical holdings

Filing-backed snapshots and historical-year availability.

Historical holdings

Resolve a filing-backed historical snapshot

Return the latest supported holdings snapshot on or before the requested date without lookahead.

GET/api/v1/historical/holdings

API key requiredFiling-backedBillable: per returned holding

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	ETF or fund ticker symbol.`IWM`
`at`Optional	`ISO 8601 date`	Optional requested historical date. The API returns the latest supported snapshot on or before it.`2008-06-30`
`limit`Optional	`integer`	Maximum holdings to return after descending-weight sorting.`25`
`tickerMapping`Optional	`none \| partial \| full`	Controls identifier-to-ticker mapping. Use full when downstream analysis needs maximum ticker coverage.`full`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/historical/holdings?ticker=IWM&at=2008-06-30&tickerMapping=full' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`ticker`	`string`	The ETF ticker that was resolved for this request.
`asOf`	`date`	The snapshot date that was returned.
`source`Optional	`string`	A source label when the resolved snapshot has one.
`holdings[]`	`Holding[]`	Holdings sorted by descending weight. The optional limit is applied after sorting.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/historical/holdings" \
  --get \
  --data-urlencode "ticker=SPY" \
  --data-urlencode "at=2024-06-30" \
  --data-urlencode "limit=25" \
  --data-urlencode "tickerMapping=full" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Historical coverage

Check historical-year availability

Inspect which historical years have an available supported filing snapshot before requesting a historical table or report.

GET/api/v1/historical/coverage

API key requiredAvailability onlyFiling coverage

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	ETF or fund ticker symbol to check.`SPY`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/historical/coverage?ticker=SPY' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`lookup`	`CoverageLookup`	Coverage state and the metadata available for the requested data family.
`lookup.status`	`string`	Current lookups use fresh, cached, stale, or missing. Historical lookups can use mapped, mixed, legacy_only, missing, or scanning.
`lookup.asOf`Optional	`date`	The latest available snapshot date for a current lookup.
`lookup.yearCoverage`Optional	`object`	Historical-year availability and per-year report details for a historical lookup.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/historical/coverage" \
  --get \
  --data-urlencode "ticker=SPY" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Reports

Portfolio reports

Reports retain the complete holdings response and add portfolio or comparison statistics from ticker-mapped rows.

Current report

Return a complete current portfolio report

Get the full enriched holdings table plus portfolio statistics, classifications, and valuation analysis for the latest available snapshot.

GET/api/v1/reports/current

API key requiredFull holdings tableBillable: per returned holding

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	ETF or fund ticker symbol.`SPY`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/reports/current?ticker=SPY' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`reportType`	`"portfolio"`	Identifies a one-portfolio report.
`endpoint`	`"current" \| "historical"`	The data family that produced the report.
`requested`	`ReportRequest`	Normalized ticker and optional requested historical date.
`generatedAt`	`timestamp`	When the API assembled the report.
`portfolio`	`PortfolioReport`	The full holdings table and derived analysis for the requested ETF.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/reports/current" \
  --get \
  --data-urlencode "ticker=SPY" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Historical report

Return a complete historical portfolio report

Get a filing-backed full holdings table and derived analysis for the latest supported snapshot on or before an optional historical date.

GET/api/v1/reports/historical

API key requiredFull holdings tableBillable: per returned holding

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	ETF or fund ticker symbol.`SPY`
`date`Optional	`YYYY-MM-DD`	Optional requested historical date. The API resolves the nearest supported snapshot on or before it.`2024-06-30`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/reports/historical?ticker=SPY&date=2024-06-30' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`reportType`	`"portfolio"`	Identifies a one-portfolio report.
`endpoint`	`"current" \| "historical"`	The data family that produced the report.
`requested`	`ReportRequest`	Normalized ticker and optional requested historical date.
`generatedAt`	`timestamp`	When the API assembled the report.
`portfolio`	`PortfolioReport`	The full holdings table and derived analysis for the requested ETF.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/reports/historical" \
  --get \
  --data-urlencode "ticker=SPY" \
  --data-urlencode "date=2024-06-30" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Current comparison

Compare two current ETF portfolios

Return both complete current holdings tables plus shared positions, unique positions, weighted overlap, classifications, and valuation comparisons.

GET/api/v1/reports/current/comparison

API key requiredTwo full portfoliosBillable: both tables

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	Primary ETF ticker symbol.`SPY`
`comparison`Required	`string`	ETF ticker symbol to compare with ticker.`QQQ`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/reports/current/comparison?ticker=SPY&comparison=QQQ' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`reportType`	`"comparison"`	Identifies a two-portfolio report.
`endpoint`	`"current" \| "historical"`	The data family used for both portfolios.
`requested`	`ReportRequest`	Normalized primary ticker, comparison ticker, and historical date when applicable.
`portfolios.ticker`	`PortfolioReport`	Full enriched holdings table and analysis for ticker.
`portfolios.comparison`	`PortfolioReport`	Full enriched holdings table and analysis for comparison.
`analysis`	`ComparisonAnalysis`	Shared and unique rows, overlap counts, allocation deltas, classifications, and valuations.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/reports/current/comparison" \
  --get \
  --data-urlencode "ticker=SPY" \
  --data-urlencode "comparison=QQQ" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Historical comparison

Compare two historical ETF portfolios

Resolve comparable filing-backed snapshots on or before a requested date and return both full portfolios with overlap analysis.

GET/api/v1/reports/historical/comparison

API key requiredTwo full portfoliosBillable: both tables

Request

Query parameters

Name	Type	Description
`ticker`Required	`string`	Primary ETF ticker symbol.`SPY`
`comparison`Required	`string`	ETF ticker symbol to compare with ticker.`QQQ`
`date`Required	`YYYY-MM-DD`	Requested historical date. Each ETF resolves to its latest supported snapshot on or before this date.`2024-06-30`

curl --request GET \
  --url 'https://etf-holdings.com/api/v1/reports/historical/comparison?ticker=SPY&comparison=QQQ&date=2024-06-30' \
  --header 'Authorization: Bearer $ETF_HOLDINGS_API_KEY'

Response

Response fields

Field	Type	Description
`reportType`	`"comparison"`	Identifies a two-portfolio report.
`endpoint`	`"current" \| "historical"`	The data family used for both portfolios.
`requested`	`ReportRequest`	Normalized primary ticker, comparison ticker, and historical date when applicable.
`portfolios.ticker`	`PortfolioReport`	Full enriched holdings table and analysis for ticker.
`portfolios.comparison`	`PortfolioReport`	Full enriched holdings table and analysis for comparison.
`analysis`	`ComparisonAnalysis`	Shared and unique rows, overlap counts, allocation deltas, classifications, and valuations.

Live request

Run this endpoint

Example

curl "https://etf-holdings.com/api/v1/reports/historical/comparison" \
  --get \
  --data-urlencode "ticker=SPY" \
  --data-urlencode "comparison=QQQ" \
  --data-urlencode "date=2024-06-30" \
  -H "Authorization: Bearer $ETF_HOLDINGS_API_KEY"

Schemas

Shared response objects

Fields shared by holdings and report responses. Enrichment is optional and may have a different as-of date.

Holding

A source row in a holdings table. Reports retain these rows even when some enrichment is unavailable.

Field	Type	Description
`weight`	`number \| null`	Portfolio weight as a decimal fraction.
`identifiers`	`HoldingIdentifiers`	Sparse public identifiers for the source row.
`classification`Optional	`HoldingClassification`	Available sector, industry-group, and industry enrichment.
`valuation`Optional	`HoldingValuation`	Available valuation enrichment. Its asOf date can differ from the holdings snapshot.

HoldingIdentifiers

Resolved public identifiers. Fields are omitted when the source or reference data does not provide them.

Field	Type	Description
`ticker`Optional	`string`	Resolved security ticker.
`name`Optional	`string`	Resolved security name.
`original`Optional	`string`	Source-row identifier or name retained for traceability.
`cusip`Optional	`string`	CUSIP when public identifier visibility permits it.
`isin`Optional	`string`	ISIN when public identifier visibility permits it.
`cik`Optional	`string`	SEC central index key.
`lei`Optional	`string`	Legal entity identifier.
`sedol`Optional	`string`	SEDOL identifier.
`figi`Optional	`string`	Financial Instrument Global Identifier.
`compositeFigi`Optional	`string`	Composite FIGI for the resolved security.
`shareClassFigi`Optional	`string`	Share-class FIGI for the resolved security.
`identifier`Optional	`string`	Provider-supplied identifier when available.

HoldingClassification

GICS-style classification enrichment for a mapped security.

Field	Type	Description
`sector`Optional	`string`	Sector label.
`industryGroup`Optional	`string`	Industry-group label.
`industry`Optional	`string`	Industry label.

HoldingValuation

Point-in-time valuation enrichment for a mapped security.

Field	Type	Description
`priceToEarnings`Optional	`number`	Price-to-earnings ratio.
`priceToBook`Optional	`number`	Price-to-book ratio.
`priceToSales`Optional	`number`	Price-to-sales ratio.
`asOf`Optional	`date`	Valuation provider as-of date.

CoverageLookup

Current and historical coverage share these core fields; the calendar applies to current lookups and filing fields apply to historical lookups.

Field	Type	Description
`ticker`	`string`	Requested ETF ticker.
`status`	`string`	Current: fresh, cached, stale, or missing. Historical: mapped, mixed, legacy_only, missing, or scanning.
`ok`	`boolean`	Whether the relevant data family has confirmed coverage.
`message`	`string`	Human-readable coverage result.
`code`Optional	`string \| null`	Current coverage warning or miss code.
`provider`Optional	`string \| null`	Current holdings provider.
`asOf`Optional	`date \| null`	Current holdings snapshot date.
`calendar`Optional	`CurrentAvailabilityCalendar \| null`	Current availability across the returned date window.
`matchCount`Optional	`integer`	Historical fund-record matches.
`lookupSource`Optional	`string \| null`	Historical ticker-mapping source.
`postNport`Optional	`HistoricalCoverageCheck`	Post-2019 filing availability.
`preNport`Optional	`HistoricalCoverageCheck`	Pre-2019 filing availability or applicability.
`yearCoverage`Optional	`HistoricalYearCoverage`	Per-year historical filing coverage.
`listingStartYear`Optional	`integer`	Earliest listed year from reference metadata.

CurrentAvailabilityCalendar

The recent-date coverage window returned by current coverage checks.

Field	Type	Description
`startDate`	`date`	First date in the coverage window.
`endDate`	`date`	Last date in the coverage window.
`totalDays`	`integer`	Number of dates in the window.
`availableDays`	`integer`	Dates served by a current cached snapshot.
`days`	`CurrentAvailabilityDay[]`	Coverage state for every date in the window.

CurrentAvailabilityDay

Current availability for one calendar date.

Field	Type	Description
`date`	`date`	Date being checked.
`status`	`"snapshot" \| "covered" \| "missing"`	Direct snapshot, coverage from an earlier snapshot, or no cached coverage.
`sourceAsOf`	`date \| null`	Snapshot date serving this calendar date.
`label`	`string`	Human-readable date result.

HistoricalCoverageCheck

A post-NPORT or pre-NPORT coverage result. Some dates and metadata apply to only one check type.

Field	Type	Description
`status`	`string`	available, missing, pending, error, or not_applicable.
`ok`	`boolean`	Whether this period has confirmed coverage.
`title`	`string`	Coverage period title.
`label`	`string`	Public date or year-range label.
`message`	`string`	Human-readable coverage result.
`code`Optional	`string \| null`	Miss or temporary error code.
`asOf`	`date \| null`	Confirmed report date, when one is available.
`sourceForm`	`string \| null`	Filing form that supplied the report.
`matchCount`Optional	`integer`	Matching post-NPORT fund records.
`lookupSource`Optional	`string \| null`	Ticker-mapping source for post-NPORT coverage.
`reportDateStart`Optional	`date`	Start of the public post-NPORT report period.
`filingDateStart`Optional	`date`	Start of the public post-NPORT filing period.
`probeDate`Optional	`date`	Pre-NPORT probe date.
`startYear`Optional	`integer`	Reference listing-start year when pre-NPORT is not applicable.

HistoricalYearCoverage

Historical filing availability across the returned year range.

Field	Type	Description
`startYear`	`integer`	First year in the scan.
`endYear`	`integer`	Last year in the scan.
`totalYears`	`integer`	Number of year entries.
`availableYearCount`	`integer`	Years with a confirmed usable report.
`pendingYearCount`	`integer`	Years still being checked.
`parseFailureYearCount`	`integer`	Years with a matched filing that could not be parsed.
`complete`	`boolean`	Whether no year remains pending.
`source`	`string \| null`	Coverage source, such as cache, when available.
`years`	`HistoricalCoverageYear[]`	One entry per year, newest first.

HistoricalCoverageYear

Historical filing coverage for one calendar year.

Field	Type	Description
`year`	`integer`	Calendar year.
`status`	`"available" \| "pending" \| "missing"`	Confirmed, still checking, or no usable filing confirmed.
`sourceForm`	`string \| null`	Filing form that supplied the report.
`reportDate`	`date \| null`	Resolved filing as-of date.
`filingDate`	`date \| null`	SEC filing date.
`holdingsCount`	`integer \| null`	Parsed holdings count when available.
`requestedYear`	`integer \| null`	Year used for the coverage probe.
`requestedAt`	`timestamp \| null`	Requested timestamp for the coverage probe.
`parseFailure`	`HistoricalParseFailure \| null`	Parsing details when a filing matched but did not yield a usable table.
`label`	`string`	Human-readable year result.

HistoricalParseFailure

Details for a matched historical filing that could not be parsed into usable holdings.

Field	Type	Description
`code`	`string`	Parser failure code.
`message`	`string \| null`	Parser failure message.
`accessionNumber`	`string \| null`	SEC accession number.
`form`	`string \| null`	SEC filing form.
`filingDate`	`date \| null`	SEC filing date.
`reportDate`	`date \| null`	Filing report date.
`sourceUrl`	`string \| null`	Source document URL.
`filingIndexUrl`	`string \| null`	SEC filing index URL.
`lookupMode`	`string \| null`	Historical lookup mode used for the filing.

PortfolioReport

The portfolio object in a single report or either side of a comparison report.

Field	Type	Description
`ticker`	`string`	Resolved ETF ticker.
`asOf`	`date`	Resolved snapshot date.
`source`Optional	`string`	Source label when available.
`holdings`	`Holding[]`	Complete enriched public holdings table returned for this portfolio.
`enrichment`	`ReportEnrichment`	Enrichment status plus ticker coverage counts.
`analysis`	`PortfolioAnalysis`	Counts, mapped-row coverage, statistics, and sector, industry-group, industry, and valuation analysis.

ReportEnrichment

Ticker-level enrichment coverage for a report portfolio.

Field	Type	Description
`status`	`"ready" \| "partial" \| "empty" \| "unavailable"`	Overall enrichment availability.
`requestedTickers`	`integer`	Mapped tickers requested from enrichment providers.
`classifiedTickers`	`integer`	Mapped tickers with classification data.
`valuedTickers`	`integer`	Mapped tickers with valuation data.

PortfolioAnalysis

Derived from the full holdings table after ticker-mapped rows are normalized. Classification and valuation side B is empty for a single portfolio.

Field	Type	Description
`holdingsCount`	`integer`	All source rows in the returned holdings table.
`mappedHoldingsCount`	`integer`	Distinct ticker-mapped positions after duplicate rows are combined.
`mappedHoldingRowCount`	`integer`	Source rows with a mapped ticker.
`unmappedHoldingRowCount`	`integer`	Source rows without a mapped ticker.
`statistics`	`PortfolioStatistics \| null`	Concentration and exposure statistics when weighted mapped positions are present.
`classifications`	`ClassificationBreakdown`	Sector, industry-group, and industry breakdowns.
`valuations`	`ValuationAnalysis`	P/E, P/B, and P/S aggregates and buckets.

PortfolioStatistics

Weight-based statistics for normalized mapped positions.

Field	Type	Description
`largestHolding`	`NormalizedHolding`	Largest position by absolute weight.
`topTenConcentration`	`number`	Sum of absolute weights for the ten largest positions.
`grossExposure`	`number`	Sum of absolute mapped weights.
`netExposure`	`number`	Sum of signed mapped weights.

NormalizedHolding

A ticker-mapped position used for report analysis after duplicate source rows are combined.

Field	Type	Description
`ticker`	`string`	Mapped security ticker.
`name`	`string`	First available resolved security name; may be empty.
`weight`	`number \| null`	Combined position weight.

ClassificationBreakdown

Parallel sector, industry-group, and industry breakdowns. A is the requested ticker; B is the comparison ticker, or zero for a single portfolio.

Field	Type	Description
`sector`	`ClassificationDimension`	Sector allocation and coverage.
`industryGroup`	`ClassificationDimension`	Industry-group allocation and coverage.
`industry`	`ClassificationDimension`	Industry allocation and coverage.

ClassificationDimension

Allocation buckets and classified-row coverage for one classification dimension.

Field	Type	Description
`buckets`	`ClassificationBucket[]`	Classification labels, including Unclassified when present.
`coverage`	`ClassificationCoverage`	Classified weight and row coverage for each side.

ClassificationBucket

One sector, industry group, or industry allocation bucket.

Field	Type	Description
`label`	`string`	Classification label.
`weightA`	`number`	Absolute mapped weight for the requested ticker.
`weightB`	`number`	Absolute mapped weight for the comparison ticker.
`countA`	`integer`	Source-row count for the requested ticker.
`countB`	`integer`	Source-row count for the comparison ticker.

ClassificationCoverage

Classified weight and row counts for a classification dimension.

Field	Type	Description
`weightA`	`number`	Classified absolute weight for the requested ticker.
`weightB`	`number`	Classified absolute weight for the comparison ticker.
`countA`	`integer`	Classified source rows for the requested ticker.
`countB`	`integer`	Classified source rows for the comparison ticker.
`totalA`	`integer`	All source rows for the requested ticker.
`totalB`	`integer`	All source rows for the comparison ticker.

ValuationAnalysis

Parallel valuation analysis for price-to-earnings, price-to-book, and price-to-sales.

Field	Type	Description
`priceToEarnings`	`ValuationMetric`	P/E aggregate and buckets.
`priceToBook`	`ValuationMetric`	P/B aggregate and buckets.
`priceToSales`	`ValuationMetric`	P/S aggregate and buckets.

ValuationMetric

One valuation ratio for the requested ticker and comparison ticker, or an empty B side for a single portfolio.

Field	Type	Description
`label`	`string`	Display label: P/E, P/B, or P/S.
`a`	`ValuationMetricSide`	Requested ticker aggregate.
`b`	`ValuationMetricSide`	Comparison ticker aggregate; empty for a single portfolio.
`buckets`	`ValuationBucket[]`	Weight and row counts by valuation band.

ValuationMetricSide

Weighted valuation aggregate and provider coverage for one portfolio.

Field	Type	Description
`value`	`number \| null`	Weighted harmonic ratio when positive values are available.
`coverage`	`number`	Share of absolute row weight covered by the metric.
`count`	`integer`	Rows with a numeric metric.
`total`	`integer`	Rows considered for the metric.
`asOf`	`date \| null`	Latest valuation as-of date among covered rows.

ValuationBucket

One valuation-band allocation bucket.

Field	Type	Description
`label`	`string`	Valuation band label.
`weightA`	`number`	Absolute mapped weight in the band for the requested ticker.
`weightB`	`number`	Absolute mapped weight in the band for the comparison ticker.
`countA`	`integer`	Rows in the band for the requested ticker.
`countB`	`integer`	Rows in the band for the comparison ticker.

ComparisonAnalysis

Mapped-ticker comparison metrics. Full source rows remain available in both portfolio tables.

Field	Type	Description
`snapshotA`	`ComparisonSnapshot`	Mapped-ticker summary for the requested ticker.
`snapshotB`	`ComparisonSnapshot`	Mapped-ticker summary for the comparison ticker.
`shared`	`SharedHolding[]`	Mapped securities held by both portfolios, with both weights and their delta.
`uniqueA`	`NormalizedHolding[]`	Mapped securities unique to the requested ticker.
`uniqueB`	`NormalizedHolding[]`	Mapped securities unique to the comparison ticker.
`sharedTickerCount`	`integer`	Number of shared mapped tickers.
`uniqueTickerCountA`	`integer`	Mapped tickers unique to the requested ticker.
`uniqueTickerCountB`	`integer`	Mapped tickers unique to the comparison ticker.
`weightedOverlap`	`number`	Sum of the lower same-direction weight for shared mapped positions.
`classifications`	`ClassificationBreakdown`	Sector, industry-group, and industry allocation comparisons.
`valuations`	`ValuationAnalysis`	P/E, P/B, and P/S comparisons.

ComparisonSnapshot

Mapped-ticker summary for one side of a comparison.

Field	Type	Description
`ticker`	`string`	Resolved ETF ticker.
`asOf`	`date`	Resolved snapshot date.
`holdingsCount`	`integer`	Distinct mapped tickers after duplicate rows are combined.
`mappedHoldingRowCount`	`integer`	Source rows with a mapped ticker.
`unmappedHoldingRowCount`	`integer`	Source rows without a mapped ticker.
`statistics`	`PortfolioStatistics \| null`	Concentration and exposure statistics for mapped positions.

SharedHolding

A ticker-mapped position present in both portfolios.

Field	Type	Description
`ticker`	`string`	Shared security ticker.
`name`	`string`	First available resolved security name; may be empty.
`weightA`	`number \| null`	Combined weight in the requested ticker.
`weightB`	`number \| null`	Combined weight in the comparison ticker.
`difference`	`number \| null`	weightA minus weightB.
`absoluteDifference`	`number \| null`	Absolute value of difference.
`combinedWeight`	`number`	Sum of absolute weights across both portfolios.
`sameDirection`	`boolean`	Whether both nonzero weights have the same sign.

ReportRequest

Normalized report query parameters returned with each report.

Field	Type	Description
`ticker`	`string`	Primary requested ETF ticker.
`comparison`Optional	`string`	Comparison ticker for a comparison report.
`date`	`date \| null`	Requested historical date, or null for current reports.

ErrorResponse

Response body for a non-successful API request.

Field	Type	Description
`error`	`ApiError`	Structured API error.

ApiError

Structured error returned with the HTTP status code.

Field	Type	Description
`code`	`string`	Machine-readable error code.
`message`	`string`	Human-readable error message.
`requestId`	`string`	Request identifier for support and troubleshooting.
`details`Optional	`object`	Additional details for exposed client errors.

Support

Coverage and data questions

Include the ticker, date, and requestId.

Contact support