api-ninjas-com Institutional Holdings API

openapi: 3.2.0
info:
  title: Ninjas Institutional Holdings API
  description: 'Combined OpenAPI specification for every API Ninjas endpoint. Requests go to https://api.api-ninjas.com with an `X-Api-Key` header; get a free key at https://api-ninjas.com/register. Human-readable docs: https://api-ninjas.com/api. Index for LLMs: https://api-ninjas.com/llms.txt.'
  version: 1.0.0
  contact:
    name: API Ninjas
    url: https://api-ninjas.com
  license:
    name: Proprietary
servers:
- url: https://api.api-ninjas.com
  description: API Ninjas Production
security:
- ApiKeyAuth: []
tags:
- name: Institutional Holdings
  description: The Institutional Holdings API exposes institutional investment-manager holdings parsed from SEC Form 13F-HR filings, sourced directly from SEC EDGAR. Free accounts can query the most recent quarter; historical quarters and the analytics endpoints require a paid plan.
paths:
  /v1/institutionalholdings:
    get:
      tags:
      - Institutional Holdings
      summary: Get the full 13F portfolio of an institutional manager for a quarter
      description: Returns an institutional manager's full 13F portfolio for a quarter. Requires `cik` or `manager_name`. For every holder of a single stock use /institutionalownership.
      operationId: getInstitutionalHoldings
      parameters:
      - name: cik
        in: query
        required: false
        description: Manager SEC Central Index Key (e.g. 1067983). Either cik or manager_name is required.
        schema:
          type: string
      - name: manager_name
        in: query
        required: false
        description: Exact manager name (alternative to cik).
        schema:
          type: string
      - name: period
        in: query
        required: false
        description: Quarter-end date (YYYY-MM-DD). Defaults to the latest quarter; free tier is limited to the most recent quarter.
        schema:
          type: string
      - name: ticker
        in: query
        required: false
        description: Filter the portfolio to a single holding by ticker.
        schema:
          type: string
      - name: cusip
        in: query
        required: false
        description: Filter the portfolio to a single holding by CUSIP.
        schema:
          type: string
      - name: put_call
        in: query
        required: false
        description: put or call to filter option positions.
        schema:
          type: string
          enum:
          - put
          - call
      - name: min_value
        in: query
        required: false
        description: Minimum reported market value (USD).
        schema:
          type: integer
      - name: max_value
        in: query
        required: false
        description: Maximum reported market value (USD).
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort order: value (default), shares, percent_of_portfolio, or issuer_name.'
        schema:
          type: string
          enum:
          - value
          - shares
          - percent_of_portfolio
          - issuer_name
      - name: change_type
        in: query
        required: false
        description: 'Comma-separated quarter-over-quarter filter: new, sold_out, increased, decreased, unchanged. Business/Professional/annual plans only. Premium only.'
        schema:
          type: string
      - name: group_by
        in: query
        required: false
        description: sector for a sector-allocation rollup. Business/Professional/annual plans only. Premium only.
        schema:
          type: string
          enum:
          - sector
      - name: limit
        in: query
        required: false
        description: Maximum results to return. Default 50, max 1000.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Number of results to skip for pagination.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/InstitutionalHolding'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
  /v1/institutionalownership:
    get:
      tags:
      - Institutional Holdings
      summary: Get every institution holding a given stock for a quarter
      description: Lists every institution holding a given stock in a quarter. Requires `ticker` or `cusip`. For one manager's entire portfolio use /institutionalholdings.
      operationId: getInstitutionalOwnership
      parameters:
      - name: ticker
        in: query
        required: false
        description: Ticker symbol (e.g. AAPL). Either ticker or cusip is required. Share classes and preferred shares can be written in any common form, e.g. BRK.B, BRK-B, BRK/B or BRKB, and BAC.PRL or BAC-PL.
        schema:
          type: string
      - name: cusip
        in: query
        required: false
        description: 9-character CUSIP (alternative to ticker).
        schema:
          type: string
      - name: period
        in: query
        required: false
        description: Quarter-end date (YYYY-MM-DD). Defaults to the latest; free tier is limited to the most recent quarter.
        schema:
          type: string
      - name: summary
        in: query
        required: false
        description: true returns the ownership-concentration aggregate instead of the holder list. Business/Professional/annual plans only. Premium only.
        schema:
          type: boolean
      - name: put_call
        in: query
        required: false
        description: put or call; long positions are returned by default.
        schema:
          type: string
          enum:
          - put
          - call
      - name: min_value
        in: query
        required: false
        description: Minimum market value (USD).
        schema:
          type: integer
      - name: min_shares
        in: query
        required: false
        description: Minimum shares held.
        schema:
          type: integer
      - name: sort
        in: query
        required: false
        description: 'Sort order: value (default), shares, or manager_name.'
        schema:
          type: string
          enum:
          - value
          - shares
          - manager_name
      - name: limit
        in: query
        required: false
        description: Maximum results to return. Default 50, max 1000.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Number of results to skip for pagination.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response. A JSON array of holder records by default, or a single ownership-concentration aggregate object when summary=true.
          content:
            application/json:
              schema:
                oneOf:
                - type: array
                  items:
                    $ref: '#/components/schemas/InstitutionalOwnershipHolder'
                - $ref: '#/components/schemas/InstitutionalOwnershipSummary'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
  /v1/institutionalinvestors:
    get:
      tags:
      - Institutional Holdings
      summary: Search 13F institutions and their filing history (Premium only)
      description: Searches the directory of 13F-filing institutions by name, CIK or quarter and returns their filing history rather than positions. Requires a premium subscription.
      operationId: getInstitutionalInvestors
      parameters:
      - name: name
        in: query
        required: false
        description: Substring search of institution names; returns directory records.
        schema:
          type: string
      - name: cik
        in: query
        required: false
        description: Returns that institution's filing history - one record per quarter.
        schema:
          type: string
      - name: period
        in: query
        required: false
        description: Quarter-end date (YYYY-MM-DD); returns every institution that filed for that quarter.
        schema:
          type: string
      - name: period_list
        in: query
        required: false
        description: true enumerates the available quarters with filing counts.
        schema:
          type: boolean
      - name: limit
        in: query
        required: false
        description: Maximum results to return. Default 50, max 1000.
        schema:
          type: integer
      - name: offset
        in: query
        required: false
        description: Number of results to skip for pagination.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response. Directory records when searching by name, filing records by cik or period, or quarter records with period_list=true.
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/InstitutionalInvestorDirectoryRecord'
                  - $ref: '#/components/schemas/InstitutionalInvestorFilingRecord'
                  - $ref: '#/components/schemas/InstitutionalInvestorQuarterRecord'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
  /v1/institutionalmovers:
    get:
      tags:
      - Institutional Holdings
      summary: Get the biggest institutional buys and exits per quarter (Premium only)
      description: Ranks the largest institutional new buys, exits, adds or trims for a quarter, market-wide or within one institution. Requires a premium subscription.
      operationId: getInstitutionalMovers
      parameters:
      - name: mover_type
        in: query
        required: false
        description: new_buys (default), exits, adds, or trims.
        schema:
          type: string
          enum:
          - new_buys
          - exits
          - adds
          - trims
      - name: period
        in: query
        required: false
        description: Quarter-end date (YYYY-MM-DD); defaults to the latest quarter.
        schema:
          type: string
      - name: cik
        in: query
        required: false
        description: Rank the moves within a single institution instead of market-wide.
        schema:
          type: string
      - name: limit
        in: query
        required: false
        description: Number of ranked rows to return. Default 50, max 1000.
        schema:
          type: integer
      responses:
        '200':
          description: Successful response. A ranked JSON array of market-wide leaderboard rows, or per-position rows for a single institution when cik is supplied.
          content:
            application/json:
              schema:
                type: array
                items:
                  oneOf:
                  - $ref: '#/components/schemas/InstitutionalMoverMarketRecord'
                  - $ref: '#/components/schemas/InstitutionalMoverManagerRecord'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
components:
  schemas:
    InstitutionalMoverManagerRecord:
      type: object
      description: Per-institution row returned when cik is supplied; each row is one position.
      properties:
        ticker:
          type: string
          description: Ticker symbol of the security.
          example: AAPL
        cusip:
          type: string
          description: CUSIP of the security.
          example: 037833100
        issuer_name:
          type: string
          description: Name of the security's issuer.
          example: APPLE INC
        share_change:
          type: integer
          description: Change in shares held versus the prior quarter.
          example: -100000000
        share_change_percent:
          type: number
          description: Percent change in shares held versus the prior quarter.
          example: -25
        market_value:
          type: integer
          description: Reported market value this quarter (whole USD).
          example: 65010000000
        prior_market_value:
          type: integer
          description: Reported market value the prior quarter (whole USD).
          example: 75000000000
        rank:
          type: integer
          description: Position in the ranking.
          example: 1
    InstitutionalMoverMarketRecord:
      type: object
      description: Market-wide leaderboard row.
      properties:
        period:
          type: string
          description: Quarter-end date of the move (YYYY-MM-DD).
          example: '2025-03-31'
        mover_type:
          type: string
          description: 'The type of move: new_buys, exits, adds, or trims.'
          example: new_buys
        ticker:
          type: string
          description: Ticker symbol of the security.
          example: NVDA
        cusip:
          type: string
          description: CUSIP of the security.
          example: 67066G104
        issuer_name:
          type: string
          description: Name of the security's issuer.
          example: NVIDIA CORP
        managers_adding:
          type: integer
          description: 'Count of institutions making this move (the field name reflects the mover_type: managers_adding, managers_exiting, or managers_trimming).'
          example: 540
        managers_exiting:
          type: integer
          description: Count of institutions exiting the position. Which of managers_adding, managers_exiting or managers_trimming is returned depends on mover_type.
        managers_trimming:
          type: integer
          description: Count of institutions trimming the position. Which of managers_adding, managers_exiting or managers_trimming is returned depends on mover_type.
        aggregate_share_change:
          type: integer
          description: Summed share change across those institutions.
          example: 88000000
        aggregate_value_change:
          type: integer
          description: Summed value change across those institutions (whole USD).
          example: 9600000000
        rank:
          type: integer
          description: Position on the leaderboard.
          example: 1
    InstitutionalInvestorFilingRecord:
      type: object
      description: Filing record returned when querying by cik or period.
      properties:
        manager_name:
          type: string
          description: Institution that filed.
          example: BERKSHIRE HATHAWAY INC
        cik:
          type: string
          description: Institution Central Index Key (zero-padded to 10 digits).
          example: 0001067983
        period:
          type: string
          description: Quarter-end date of the filing (YYYY-MM-DD).
          example: '2025-03-31'
        filing_date:
          type: string
          description: Date the filing was made with the SEC.
          example: '2025-05-15'
        form_type:
          type: string
          description: 13F-HR or 13F-HR/A.
          example: 13F-HR
        is_amendment:
          type: boolean
          description: Whether the filing is an amendment.
          example: false
        amendment_type:
          type:
          - string
          - 'null'
          description: Amendment details, if the filing is an amendment.
          example: null
        num_holdings:
          type: integer
          description: Holdings count of the filing.
          example: 38
        portfolio_value:
          type: integer
          description: Total value of the filing (whole USD).
          example: 261000000000
        accession_number:
          type: string
          description: SEC accession number.
          example: 0000950123-25-005701
        sec_filing_url:
          type: string
          description: Link to the filing index on SEC EDGAR.
          example: https://www.sec.gov/Archives/edgar/data/1067983/000095012325005701/0000950123-25-005701-index.htm
    InstitutionalHolding:
      type: object
      properties:
        manager_name:
          type: string
          description: Institutional manager (filer) name.
          example: BERKSHIRE HATHAWAY INC
        cik:
          type: string
          description: Manager Central Index Key (zero-padded to 10 digits).
          example: 0001067983
        period:
          type: string
          description: Quarter-end date of the report (YYYY-MM-DD).
          example: '2025-03-31'
        filing_date:
          type: string
          description: Date the 13F was filed with the SEC.
          example: '2025-05-15'
        issuer_name:
          type: string
          description: Name of the security's issuer.
          example: APPLE INC
        ticker:
          type: string
          description: Ticker symbol, mapped from the reported CUSIP.
          example: AAPL
        cusip:
          type: string
          description: CUSIP as reported in the filing.
          example: 037833100
        security_class:
          type: string
          description: Title of class (e.g. COM).
          example: COM
        shares:
          type: integer
          description: Shares (or principal amount) held.
          example: 300000000
        share_type:
          type: string
          description: SH (shares) or PRN (principal amount).
          example: SH
        market_value:
          type: integer
          description: Reported market value in whole U.S. dollars.
          example: 65010000000
        percent_of_portfolio:
          type: number
          description: Position value as a percent of the manager's total 13F portfolio.
          example: 24.83
        put_call:
          type:
          - string
          - 'null'
          description: Put, Call.
          example: null
        investment_discretion:
          type: string
          description: SOLE, DFND, or OTR.
          example: SOLE
        voting_authority_sole:
          type: integer
          description: Shares over which the manager has sole voting authority.
          example: 300000000
        voting_authority_shared:
          type: integer
          description: Shares over which the manager has shared voting authority.
          example: 0
        voting_authority_none:
          type: integer
          description: Shares over which the manager has no voting authority.
          example: 0
        is_new:
          type: boolean
          description: true if the manager opened this position in the reported quarter. Premium only.
          example: false
        share_change:
          type: integer
          description: Change in shares held versus the prior quarter. Premium only.
          example: -100000000
        share_change_percent:
          type: number
          description: Percent change in shares held versus the prior quarter. Premium only.
          example: -25
        sec_filing_url:
          type: string
          description: Link to the filing index on SEC EDGAR.
          example: https://www.sec.gov/Archives/edgar/data/1067983/000095012325005701/0000950123-25-005701-index.htm
        data_source:
          type: string
          description: Source of the record.
          example: sec_edgar
        last_updated:
          type: integer
          description: Unix timestamp (UTC) of the last record refresh.
          example: 1747353600
    InstitutionalInvestorDirectoryRecord:
      type: object
      description: Directory record returned when searching by name.
      properties:
        manager_name:
          type: string
          description: Institution name.
          example: BERKSHIRE HATHAWAY INC
        cik:
          type: string
          description: Institution Central Index Key (zero-padded to 10 digits).
          example: 0001067983
        latest_period:
          type: string
          description: Most recent quarter reported (YYYY-MM-DD).
          example: '2025-03-31'
        latest_filing_date:
          type: string
          description: Date the most recent quarter was filed.
          example: '2025-05-15'
        num_holdings:
          type: integer
          description: Holdings count of the latest filing.
          example: 38
        portfolio_value:
          type: integer
          description: Total portfolio value of the latest filing (whole USD).
          example: 261000000000
        first_period:
          type: string
          description: Earliest quarter on file for the institution.
          example: '2013-12-31'
        data_source:
          type: string
          description: Source of the record.
          example: sec_edgar
    InstitutionalOwnershipSummary:
      type: object
      description: Ownership-concentration aggregate returned when summary=true. Premium only.
      properties:
        institutional_holders_count:
          type: integer
          description: Number of institutions holding the stock this quarter.
          example: 4820
        total_shares_held:
          type: integer
          description: Aggregate shares held across all institutional holders.
          example: 9200000000
        total_market_value:
          type: integer
          description: Aggregate market value across all institutional holders (whole USD).
          example: 1990000000000
        new_positions_count:
          type: integer
          description: Holders opening a position this quarter.
          example: 210
        closed_positions_count:
          type: integer
          description: Holders fully exiting this quarter.
          example: 95
        increased_positions_count:
          type: integer
          description: Holders adding this quarter.
          example: 1850
        decreased_positions_count:
          type: integer
          description: Holders trimming this quarter.
          example: 2100
        net_share_change:
          type: integer
          description: Net share change across holders versus the prior quarter.
          example: -45000000
        holders_count_change:
          type: integer
          description: Change in holder count versus the prior quarter.
          example: 115
    InstitutionalOwnershipHolder:
      type: object
      properties:
        manager_name:
          type: string
          description: Institution holding the security.
          example: VANGUARD GROUP INC
        cik:
          type: string
          description: Manager Central Index Key (zero-padded to 10 digits).
          example: 0000102909
        ticker:
          type: string
          description: Ticker symbol of the security being held.
          example: AAPL
        cusip:
          type: string
          description: CUSIP of the security being held.
          example: 037833100
        issuer_name:
          type: string
          description: Name of the security's issuer.
          example: APPLE INC
        period:
          type: string
          description: Quarter-end date of the report (YYYY-MM-DD).
          example: '2025-03-31'
        shares:
          type: integer
          description: Shares held.
          example: 1380000000
        market_value:
          type: integer
          description: Reported market value in whole U.S. dollars.
          example: 299000000000
        percent_of_portfolio:
          type: number
          description: Position as a percent of the manager's 13F portfolio.
          example: 4.71
        put_call:
          type:
          - string
          - 'null'
          description: Put, Call.
          example: null
        filing_date:
          type: string
          description: Date the 13F was filed with the SEC.
          example: '2025-05-14'
        sec_filing_url:
          type: string
          description: Link to the filing index on SEC EDGAR.
          example: https://www.sec.gov/Archives/edgar/data/102909/000110465925000000/0001104659-25-000000-index.htm
    InstitutionalInvestorQuarterRecord:
      type: object
      description: Quarter record returned with period_list=true.
      properties:
        quarter:
          type: string
          description: Quarter label.
          example: 2025Q1
        period:
          type: string
          description: Quarter-end date (YYYY-MM-DD).
          example: '2025-03-31'
        filing_count:
          type: integer
          description: Number of 13F filings available for the quarter.
          example: 8912
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api