> ## Documentation Index
> Fetch the complete documentation index at: https://docs.financialdatasets.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Holdings (by fund)

> Get an ETF or index fund's holdings and each position's weight, sourced direct from SEC fund holdings filings.

### Overview

Give us a fund ticker, get its full list of holdings and each position's percent of net assets. Constituents are returned sorted by weight descending, with a fund header that carries the as-of period and coverage counts.

Use this to answer "what's in SPY, and at what weight?" for index replication, exposure analysis, and overlap checks.

To get started, please create an account and grab your <b>API key</b> at [financialdatasets.ai](https://financialdatasets.ai).

You will use the API key to authenticate your API requests.

### Coverage

| Funds | Years of Coverage | Updated |
| ----- | ----------------- | ------- |
| 100   | 5+ years          | Daily   |

### The "latest" definition

Without an `as_of` filter, this endpoint returns the fund's **most recent filing**. To reconstruct a historical composition, pass `as_of=YYYY-MM-DD` and the response is the composition in effect on or before that date.

### All holdings, labeled

Every position is returned, including bonds, derivatives, and cash, each labeled with an `asset_class` (`equity`, `bond`, or `other`). Identifiers (`cusip`, `isin`, `name`) are included when available; `ticker` is `null` for securities without a US listing (e.g., many bonds and foreign holdings). To narrow the list, pass `asset_class=equity` or `asset_class=bond`.

### Find available tickers

To discover which funds are available, hit the helper endpoint:

```python Tickers theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
import requests

# free endpoint, no API key required
url = 'https://api.financialdatasets.ai/index-funds/tickers/'
response = requests.get(url)

tickers = response.json().get('tickers')
print(f'{len(tickers)} funds available')
```

### Filtering the Data

`ticker` is required. Optional filters:

* `as_of` — the composition in effect on/before this date (YYYY-MM-DD). Defaults to the latest filing.
* `asset_class` — `equity` or `bond`. Defaults to all holdings.

By default, `limit` is `50` (max `1000`). Use `offset` to page through a fund's constituents.

### Examples

<CodeGroup>
  ```python Latest holdings theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import requests

  # add your API key to the headers
  headers = {
      "X-API-KEY": "your_api_key_here"
  }

  # set your query params
  ticker = 'SPY'              # fund ticker
  limit = 50                  # number of holdings to return

  # create the URL
  url = (
      f'https://api.financialdatasets.ai/index-funds/'
      f'?ticker={ticker}'
      f'&limit={limit}'
  )

  # make API request
  response = requests.get(url, headers=headers)

  # parse holdings from the response
  holdings = response.json().get('holdings')
  ```

  ```python As-of date + equities only theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
  import requests

  # add your API key to the headers
  headers = {
      "X-API-KEY": "your_api_key_here"
  }

  # set your query params
  ticker = 'SPY'
  as_of = '2023-12-31'        # composition in effect on/before this date
  asset_class = 'equity'      # equities only

  # create the URL
  url = (
      f'https://api.financialdatasets.ai/index-funds/'
      f'?ticker={ticker}'
      f'&as_of={as_of}'
      f'&asset_class={asset_class}'
  )

  # make API request
  response = requests.get(url, headers=headers)

  # parse holdings from the response
  holdings = response.json().get('holdings')
  ```
</CodeGroup>


## OpenAPI

````yaml GET /index-funds
openapi: 3.0.1
info:
  title: Financial Datasets API
  description: >-
    Stock market API with real-time and historical financial data for 27,000+
    tickers over 30+ years. Financial statements, equity prices, insider trades,
    SEC filings, and more.
  version: 1.0.0
  license:
    name: MIT
    url: https://opensource.org/licenses/MIT
  contact:
    name: API Support
    url: mailto:support@financialdatasets.ai
    email: support@financialdatasets.ai
  termsOfService: https://financialdatasets.ai/terms-of-use
servers:
  - url: https://api.financialdatasets.ai/
    description: Production server
security:
  - X-API-KEY: []
tags:
  - name: Financial Statements
    description: Access to income statements, balance sheets, and cash flow statements
  - name: Market Data
    description: Real-time and historical price data
  - name: Company Information
    description: Company facts like ticker, name, and description
  - name: Earnings
    description: Earnings data and related information
  - name: News
    description: Real-time and historical news articles
  - name: SEC Filings
    description: SEC filings and regulatory documents
  - name: Insider Trades
    description: Insider trading activity and transactions
  - name: Activist Ownership
    description: Activist stakes from SEC Schedule 13D filings, in real time
  - name: Beneficial Ownership
    description: >-
      Holders of more than 5% of a company's shares, from SEC Schedules 13D and
      13G
  - name: Insider Ownership
    description: Insider ownership statements from SEC Forms 3 and 5
  - name: Institutional Holdings
    description: SEC-direct 13F equity holdings of institutional investment managers
  - name: Index Funds
    description: >-
      ETF and index-fund holdings, weights, and the funds that hold a given
      security
  - name: Financial Metrics
    description: Financial ratios, metrics, and key performance indicators
  - name: Macroeconomics
    description: Real-time and historical macroeconomic data like interest rates
  - name: KPIs
    description: Sector-specific operational KPIs extracted from earnings releases.
paths:
  /index-funds:
    get:
      tags:
        - Index Funds
      summary: Get ETF / index-fund holdings
      description: >-
        Query fund holdings in two directions. Provide exactly one of `ticker`
        or `holding`. `?ticker=SPY` returns a fund's constituents and each
        position's weight (the fund's latest filing by default, or the
        composition in effect on/before `as_of`). `?holding=AAPL` returns the
        funds whose latest filing holds that security, sorted by weight.
      operationId: getIndexFunds
      parameters:
        - name: ticker
          in: query
          description: >-
            The fund's ticker symbol (e.g., `SPY`). Returns that fund's
            holdings. Mutually exclusive with `holding`.
          schema:
            type: string
        - name: holding
          in: query
          description: >-
            A held security's ticker symbol (e.g., `AAPL`). Returns the funds
            whose latest filing holds it. Mutually exclusive with `ticker`.
          schema:
            type: string
        - name: as_of
          in: query
          description: >-
            Only valid with `ticker`. Returns the fund composition in effect on
            or before this date (YYYY-MM-DD). Without it, the fund's latest
            filing is returned.
          required: false
          schema:
            type: string
            format: date
        - name: asset_class
          in: query
          description: >-
            Only valid with `ticker`. Filter constituents by instrument type:
            `equity` or `bond`. Omit for all holdings.
          required: false
          schema:
            type: string
            enum:
              - equity
              - bond
        - name: limit
          in: query
          description: 'The maximum number of rows to return (default: 50, max: 1000).'
          required: false
          schema:
            type: integer
            default: 50
            maximum: 1000
        - name: offset
          in: query
          description: 'The number of rows to skip, for pagination (default: 0).'
          required: false
          schema:
            type: integer
            default: 0
      responses:
        '200':
          description: >-
            Index fund holdings response. The shape depends on the query
            direction: `ticker` returns a fund header + constituents; `holding`
            returns a security header + funds.
          content:
            application/json:
              schema:
                oneOf:
                  - $ref: '#/components/schemas/IndexFundHoldingsResponse'
                  - $ref: '#/components/schemas/IndexFundsForHoldingResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
        '404':
          $ref: '#/components/responses/NotFoundError'
components:
  schemas:
    IndexFundHoldingsResponse:
      type: object
      description: >-
        Forward response (`?ticker=...`): a fund header plus its constituents,
        sorted by weight descending.
      properties:
        ticker:
          type: string
          description: The fund ticker echoed back from the request.
        fund:
          type: object
          description: >-
            Fund header: identity, the as-of period, and coverage counts for the
            full fund (not the returned page).
          properties:
            name:
              type: string
              description: Fund name.
            cik:
              type: string
              description: The fund registrant's SEC CIK.
            asset_class:
              type: string
              description: Fund asset class (e.g., `equity`, `bond`).
            as_of:
              type: string
              format: date
              description: Reporting period of the filing the holdings are drawn from.
            filing_date:
              type: string
              format: date
              nullable: true
              description: Date the filing was submitted to the SEC.
            source:
              type: string
              description: Provenance of the holdings.
            total_net_assets:
              type: number
              nullable: true
              description: The fund's total net assets in USD (the weight denominator).
            total_holdings:
              type: integer
              description: Total number of holdings in the fund for this period.
            returned:
              type: integer
              description: Number of holdings in this page.
            offset:
              type: integer
              description: The pagination offset echoed back from the request.
        holdings:
          type: array
          items:
            $ref: '#/components/schemas/FundHolding'
    IndexFundsForHoldingResponse:
      type: object
      description: >-
        Reverse response (`?holding=...`): a security header plus the funds
        whose latest filing holds it, sorted by weight descending.
      properties:
        holding:
          type: string
          description: The held-security ticker echoed back from the request.
        security:
          type: object
          description: 'Security header: the queried security plus result counts.'
          properties:
            ticker:
              type: string
              description: The queried security ticker.
            name:
              type: string
              nullable: true
              description: Security name (null when no fund holds it).
            cusip:
              type: string
              nullable: true
              description: 9-character CUSIP, when available.
            isin:
              type: string
              nullable: true
              description: 12-character ISIN, when available.
            total_funds:
              type: integer
              description: >-
                Total funds whose latest filing holds the security (not the
                returned page).
            returned:
              type: integer
              description: Number of funds in this page.
            offset:
              type: integer
              description: The pagination offset echoed back from the request.
        funds:
          type: array
          items:
            $ref: '#/components/schemas/FundPosition'
    FundHolding:
      type: object
      description: >-
        A single constituent of a fund. Identifiers (`cusip`, `isin`, `name`)
        are included when available; `ticker` is null for securities without a
        US listing (e.g., many bonds and foreign holdings).
      properties:
        ticker:
          type: string
          nullable: true
          description: >-
            Ticker of the held security, or null for securities without a US
            listing.
        name:
          type: string
          nullable: true
          description: Name of the held security.
        cusip:
          type: string
          nullable: true
          description: 9-character CUSIP, when available.
        isin:
          type: string
          nullable: true
          description: 12-character ISIN, when available.
        weight:
          type: number
          nullable: true
          description: The position as a percent of the fund's net assets.
        market_value:
          type: number
          nullable: true
          description: Position market value in USD.
        shares:
          type: number
          nullable: true
          description: Number of shares or principal amount held.
        asset_class:
          type: string
          description: 'Friendly instrument type: `equity`, `bond`, or `other`.'
    FundPosition:
      type: object
      description: One fund's position in the queried security.
      properties:
        ticker:
          type: string
          nullable: true
          description: The fund's ticker.
        name:
          type: string
          description: Fund name.
        cik:
          type: string
          description: The fund registrant's SEC CIK.
        asset_class:
          type: string
          description: Fund asset class (e.g., `equity`, `bond`).
        as_of:
          type: string
          format: date
          description: Reporting period of the fund's latest filing.
        filing_date:
          type: string
          format: date
          nullable: true
          description: Date the filing was submitted to the SEC.
        weight:
          type: number
          nullable: true
          description: The security as a percent of this fund's net assets.
        market_value:
          type: number
          nullable: true
          description: The fund's position value in USD.
        shares:
          type: number
          nullable: true
          description: Shares or principal amount the fund holds.
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: A short error message.
        message:
          type: string
          description: A more detailed error message.
  responses:
    BadRequestError:
      description: Bad request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Bad Request
            message: Invalid request parameters
    UnauthorizedError:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Unauthorized
            message: Invalid API key provided
    PaymentRequiredError:
      description: The request requires a paid subscription
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Payment Required
            message: >-
              This endpoint requires a paid subscription. Please upgrade your
              plan.
    NotFoundError:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error: Not Found
            message: Ticker XXXX not found
  securitySchemes:
    X-API-KEY:
      type: apiKey
      name: X-API-KEY
      description: API key for authentication.
      in: header

````