> ## 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.

# Beneficial Ownership

> See every holder of more than 5% of a US public company, from SEC Schedules 13D and 13G. Activist and passive stakes with full amendment history.

### Overview

The beneficial ownership API returns the holders of more than 5% of a class of a company's shares, sourced from SEC Schedules 13D and 13G.

Both schedules report the same thing — a 5%+ stake — and differ by intent:

* **Schedule 13D** (`type=activist`): the holder may seek to influence control (proxy fights, board seats, pushing for a sale).
* **Schedule 13G** (`type=passive`): the holder certifies passive intent (typically large asset managers).

A stake can move between the two over time: an activist settles and goes passive, or a passive holder turns active. This endpoint keeps each stake's full story in one place, so you never lose a position across that transition.

You can answer questions like:

* Who owns more than 5% of this company, and how much exactly?
* Which of those holders are activists versus passive institutions?
* How has a specific holder's position changed filing by filing?

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

| Companies | Filers | History            | Updated                                                 |
| --------- | ------ | ------------------ | ------------------------------------------------------- |
| 6,400+    | 8,100+ | Since January 2025 | Activist stakes within \~1 minute; passive stakes daily |

Coverage begins in January 2025, when the SEC's structured-data mandate for Schedules 13D and 13G took effect.

### Two Ways to Query

Provide exactly one of `ticker` or `filer_cik`:

* `ticker` — who owns more than 5% of this company
* `filer_cik` — what stakes does this filer hold, across companies

By default, each stake's **current state** is returned (the most recent filing in its amendment chain). Add `history=true` to get the full chain of original filings and amendments.

### Available Tickers

You can fetch a list of companies with 5%+ holders with a `GET` request to:
[https://api.financialdatasets.ai/beneficial-ownership/tickers/](https://api.financialdatasets.ai/beneficial-ownership/tickers/)

### Available Filers

You can look up filers (and their CIKs) by owner name with a `GET` request to:
[https://api.financialdatasets.ai/beneficial-ownership/filers/?name=vanguard](https://api.financialdatasets.ai/beneficial-ownership/filers/?name=vanguard)

The `name` parameter matches owner names by prefix (case-insensitive). The response includes a `total` count of all matches alongside the returned page; the page size is controlled with `limit` (default `100`, max `1000`). If `total` is larger than the page you received, narrow the search with `name`.

### Getting Started

There are only 3 steps for making a successful API call:

1. Add your API key to the header of the request as `X-API-KEY`.
2. Add query params like `ticker` and `limit` to filter the data.
3. Execute the API request.

### Filtering the Data

You can filter the data by `ticker` or `filer_cik` (exactly one, required), plus `type`, `history`, `limit`, and `filing_date`.

**Note**: by default, `limit` is `10` (max `1000`), `type` is `null` (both activist and passive), and `history` is `false` (current stake state only).

The `type` parameter filters to `activist` (Schedule 13D) or `passive` (Schedule 13G) stakes.

The `filing_date` parameter is used to filter by when filings were submitted. For example, you can include filters like `filing_date_lte=2026-06-30` and `filing_date_gte=2026-01-01` to get filings from the first half of 2026.

The available `filing_date` operations are:

* `filing_date_lte`
* `filing_date_lt`
* `filing_date_gte`
* `filing_date_gt`
* `filing_date`

Only interested in activists? The [activist ownership API](/api/activist-ownership) is a dedicated view of the same data, pinned to activist stakes and updated in real time.

### Example (by ticker)

```python Beneficial Ownership 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 = 'NVDA'     # stock ticker
limit = 50          # number of rows to return

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

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

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

### Example (passive stakes only)

```python Beneficial Ownership 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 = 'NVDA'     # stock ticker
type = 'passive'    # 13G stakes only

# create the URL
url = (
    f'https://api.financialdatasets.ai/beneficial-ownership'
    f'?ticker={ticker}'
    f'&type={type}'
)

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

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

### Example (by filer, with history)

```python Beneficial Ownership 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
filer_cik = '915191'    # the filer's SEC CIK
history = 'true'        # include the full amendment chain

# create the URL
url = (
    f'https://api.financialdatasets.ai/beneficial-ownership'
    f'?filer_cik={filer_cik}'
    f'&history={history}'
)

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

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


## OpenAPI

````yaml GET /beneficial-ownership
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: IPOs
    description: >-
      Upcoming IPOs from SEC registration statements (Form S-1), with extracted
      pre-IPO financial statements
  - 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:
  /beneficial-ownership:
    get:
      tags:
        - Beneficial Ownership
      summary: Get beneficial ownership
      description: >-
        Get beneficial-ownership stakes (SEC Schedules 13D and 13G: holders of
        more than 5% of a class of shares), one row per reporting person. Query
        by ticker (who owns this company) or by filer_cik (what stakes does this
        filer hold); provide exactly one of the two. By default each stake's
        current state is returned; set history=true for the full amendment
        chain. Use type=activist for 13D stakes (intent to influence control) or
        type=passive for 13G stakes.
      operationId: getBeneficialOwnership
      parameters:
        - name: ticker
          in: query
          description: >-
            The ticker symbol of the subject company. Provide ticker or
            filer_cik, not both.
          required: false
          schema:
            type: string
        - name: filer_cik
          in: query
          description: >-
            The SEC CIK of the filer (the beneficial owner). Provide ticker or
            filer_cik, not both. Use the /beneficial-ownership/filers endpoint
            to look up CIKs by owner name.
          required: false
          schema:
            type: string
        - name: type
          in: query
          description: >-
            Filter by stake type: activist (Schedule 13D) or passive (Schedule
            13G).
          required: false
          schema:
            type: string
            enum:
              - activist
              - passive
        - name: history
          in: query
          description: >-
            When true, returns the full amendment history of each stake instead
            of only its current state.
          required: false
          schema:
            type: boolean
            default: false
        - name: filing_date
          in: query
          description: Filter by exact filing date in YYYY-MM-DD format.
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_gte
          in: query
          description: >-
            Filter by filing date greater than or equal to this date
            (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_lte
          in: query
          description: Filter by filing date less than or equal to this date (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_gt
          in: query
          description: Filter by filing date greater than this date (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: filing_date_lt
          in: query
          description: Filter by filing date less than this date (YYYY-MM-DD).
          required: false
          schema:
            type: string
            format: date
        - name: limit
          in: query
          description: 'The maximum number of rows to return (default: 10, max: 1000).'
          required: false
          schema:
            type: integer
            default: 10
      responses:
        '200':
          description: Beneficial ownership response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BeneficialOwnershipResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/UnauthorizedError'
        '402':
          $ref: '#/components/responses/PaymentRequiredError'
components:
  schemas:
    BeneficialOwnershipResponse:
      type: object
      properties:
        beneficial_owners:
          type: array
          items:
            $ref: '#/components/schemas/BeneficialOwner'
    BeneficialOwner:
      type: object
      properties:
        ticker:
          type: string
          nullable: true
          description: >-
            The ticker symbol of the subject company. Null when the issuer has
            no listed ticker.
        issuer_name:
          type: string
          nullable: true
          description: The name of the subject company, as written on the filing.
        issuer_cik:
          type: string
          nullable: true
          description: The SEC CIK of the subject company.
        issuer_cusip:
          type: string
          nullable: true
          description: >-
            The CUSIP (or ISIN, for some foreign issuers) of the security, as
            written on the filing.
        security_class_title:
          type: string
          nullable: true
          description: >-
            The class of securities the stake is reported against (e.g. 'Common
            Stock'). percent_of_class is relative to this class.
        filer_cik:
          type: string
          description: >-
            The SEC CIK of the filer. All rows of one filing share it; use it
            with the filer_cik query parameter to follow a filer across
            companies.
        reporting_person_name:
          type: string
          nullable: true
          description: >-
            The reporting person named on this row of the cover page. Joint
            filings list several reporting persons.
        reporting_person_cik:
          type: string
          nullable: true
          description: The SEC CIK of the reporting person, when provided.
        type_of_reporting_person:
          type: string
          nullable: true
          description: >-
            The cover-page reporting-person type code (e.g. IN for individual,
            CO for corporation, PN for partnership).
        citizenship_or_place_of_organization:
          type: string
          nullable: true
          description: >-
            The reporting person's citizenship or place of organization, as
            coded on the filing.
        form_type:
          type: string
          description: >-
            The SEC form type: SCHEDULE 13D, SCHEDULE 13D/A, SCHEDULE 13G, or
            SCHEDULE 13G/A.
        type:
          type: string
          enum:
            - activist
            - passive
          description: >-
            The stake type: activist (Schedule 13D, intent to influence control)
            or passive (Schedule 13G).
        is_amendment:
          type: boolean
          description: True when this filing amends an earlier one.
        amendment_number:
          type: integer
          nullable: true
          description: The amendment number, when the filing states one.
        filing_date:
          type: string
          format: date
          nullable: true
          description: The date the filing was submitted to the SEC.
        event_date:
          type: string
          format: date
          nullable: true
          description: The date of the event that triggered the filing obligation.
        accession_number:
          type: string
          description: >-
            The SEC accession number of the filing. All reporting persons of one
            filing share it.
        sole_voting_power:
          type: integer
          nullable: true
          description: Shares over which the reporting person has sole voting power.
        shared_voting_power:
          type: integer
          nullable: true
          description: Shares over which the reporting person shares voting power.
        sole_dispositive_power:
          type: integer
          nullable: true
          description: Shares over which the reporting person has sole power to dispose.
        shared_dispositive_power:
          type: integer
          nullable: true
          description: Shares over which the reporting person shares power to dispose.
        aggregate_amount_beneficially_owned:
          type: integer
          nullable: true
          description: Total shares beneficially owned by the reporting person.
        percent_of_class:
          type: number
          nullable: true
          description: The stake as a percent of the reported class of securities.
        purpose_of_transaction:
          type: string
          nullable: true
          description: >-
            The stated purpose of the transaction (Schedule 13D item 4). Null
            for passive stakes.
        rule_filed_under:
          type: string
          nullable: true
          description: >-
            The rule the Schedule 13G was filed under (e.g. Rule 13d-1(b)). Null
            for activist stakes.
        is_latest:
          type: boolean
          description: >-
            True when this filing is the stake's most recent state; false on
            superseded filings returned with history=true.
    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.
  securitySchemes:
    X-API-KEY:
      type: apiKey
      name: X-API-KEY
      description: API key for authentication.
      in: header

````