Earnings Feed Institutional API

openapi: 3.2.0
info:
  title: Earnings Feed Institutional API
  version: 1.0.0
  description: 'Access SEC filings, insider transactions, institutional holdings, and company data.


    ## Authentication


    All API endpoints require authentication via API key. Include your key in the Authorization header:


    ```

    Authorization: Bearer your_api_key

    ```


    ## Rate Limits


    The tier-specific per-minute limits below apply to API-key and MCP requests. Interactive documentation tokens retain a

    fixed limit of 10 requests per minute, regardless of subscription tier:


    | Tier | Requests/minute | Requests/UTC month |

    |------|-----------------|--------------------|

    | Free | 15 | 5,000 |

    | Pro | 60 | 250,000 |

    | Trader | 300 | 2,000,000 |


    The monthly allowance is account-wide and shared across API keys, interactive documentation, and MCP tool calls.


    Authenticated responses that pass the minute throttle include both minute and monthly usage headers:

    - `X-RateLimit-Limit`: Maximum requests per minute

    - `X-RateLimit-Remaining`: Remaining requests in current window

    - `X-RateLimit-Reset`: Unix timestamp when the window resets

    - `X-RateLimit-Monthly-Limit`: Requests included per UTC calendar month

    - `X-RateLimit-Monthly-Remaining`: Remaining requests in the current UTC month

    - `X-RateLimit-Monthly-Reset`: Unix timestamp for the next UTC month

    - `X-RateLimit-Monthly-Policy`: currently `hard` for every tier


    Every tier stops at its account-wide UTC monthly allowance: Free at 5,000 requests, Pro at 250,000, and Trader at

    2,000,000. Usage milestones are recorded at 70%, 90%, and 100% so integrations can upgrade before reaching the cap.


    For a minute throttle, HTTP `429` uses code `RATE_LIMITED`, `X-RateLimit-Scope: minute`, and a `Retry-After`

    header. Wait for that interval, add jitter, and cap retry attempts. A monthly cap uses code

    `MONTHLY_QUOTA_EXCEEDED`, `X-RateLimit-Scope: monthly`, reset timing, upgrade guidance, and an HTTP-date

    `Retry-After` value that points to the monthly reset; do not retry it in a loop.


    ```js

    async function fetchWithBackoff(url, options) {

    for (let attempt = 0; attempt setTimeout(resolve, retryAfter * 1000 + jitterMs));

    }

    }

    ```


    ## Pagination


    List endpoints use cursor-based pagination:

    - `limit`: Number of items per page (1-100, default 25)

    - `cursor`: Opaque cursor from previous response


    Response includes:

    - `items`: Array of results

    - `nextCursor`: Cursor for next page (null if no more)

    - `hasMore`: Whether more items exist'
  contact:
    name: Earnings Feed Support
    url: https://earningsfeed.com/support
    email: support@earningsfeed.com
  license:
    name: Proprietary
    url: https://earningsfeed.com/terms
servers:
- url: https://earningsfeed.com
  description: Production
security:
- bearerAuth: []
tags:
- name: Institutional
  description: Access institutional investment holdings from SEC Form 13F filings. Track positions held by hedge funds, mutual funds, and other institutional managers with $100M+ in assets.
paths:
  /api/v1/institutional/holdings:
    get:
      tags:
      - Institutional
      summary: List institutional holdings
      description: 'Retrieve institutional investment holdings from SEC Form 13F filings.


        ## Data Source


        Form 13F is a quarterly report filed by institutional investment managers with at least $100 million in assets under management. These filings reveal the equity holdings of major investors including hedge funds, mutual funds, pension funds, and other institutional investors.


        ## Understanding 13F Data


        ### What''s Included

        - **Equity securities** listed on US exchanges

        - **Options** (put/call positions) on such securities

        - **Convertible debt** that is convertible into equity


        ### What''s NOT Included

        - Foreign securities (unless ADRs)

        - Fixed income securities

        - Privately held investments

        - Short positions (13F only reports long positions)


        ## Key Fields


        | Field | Description |

        |-------|-------------|

        | **cusip** | 9-character security identifier (first 6 = issuer, 7-8 = issue, 9 = check digit) |

        | **value** | Market value in USD (as reported, typically in thousands) |

        | **shares** | Number of shares held |

        | **sharesType** | SH = Shares, PRN = Principal amount (for debt) |

        | **putCall** | Put, Call, or null (for common stock) |

        | **investmentDiscretion** | SOLE, DFND (defined/shared), or OTHER |

        | **votingSole/Shared/None** | Breakdown of voting authority |


        ## Filtering Strategies


        ### Find All Holders of a Stock

        ```

        ?ticker=AAPL

        ?cusip=037833100

        ?companyCik=320193

        ```


        ### Track a Specific Fund''s Portfolio

        ```

        ?managerCik=1067983 # Berkshire Hathaway

        ?managerName=Bridgewater # Partial name match

        ```


        ### Filter by Report Period

        ```

        ?reportPeriod=2024-09-30 # Exact quarter end

        ?startDate=2024-01-01&endDate=2024-12-31 # Date range

        ```


        ### Find Large Positions

        ```

        ?minValue=1000000000 # Positions worth $1B+

        ?minShares=10000000 # Positions of 10M+ shares

        ```


        ### Filter by Security Type

        ```

        ?putCall=put # Put options only

        ?putCall=call # Call options only

        ?putCall=equity # Common stock only (no options)

        ```


        ## Report Period Timing


        13F filings are due 45 days after quarter end:

        - **Q1** (Jan-Mar): Filed by May 15

        - **Q2** (Apr-Jun): Filed by Aug 14

        - **Q3** (Jul-Sep): Filed by Nov 14

        - **Q4** (Oct-Dec): Filed by Feb 14


        ## Example Use Cases


        1. **Track Warren Buffett''s moves**: Filter by `managerCik=1067983` (Berkshire)

        2. **Who owns Apple?**: Filter by `ticker=AAPL` + `minValue=1000000000`

        3. **Options activity**: Filter by `putCall=put` or `putCall=call`

        4. **New positions**: Compare `reportPeriod` across quarters

        5. **Sector analysis**: Search by `issuerName` patterns


        ## Notes


        - Values are reported as of quarter end, not filing date

        - Amendments (13F-HR/A) may update previously reported positions

        - Some managers file confidential treatment requests to delay disclosure'
      security:
      - bearerAuth: []
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 25
          description: Number of items to return (1-100)
          example: 25
        required: false
        description: Number of items to return (1-100)
        name: limit
        in: query
      - schema:
          type: string
          description: Cursor for pagination (opaque string from previous response)
          example: eyJzb3J0IjoiMjAyNC0xMS0wMVQxMjozMDowMC4wMDBaIiwiaWQiOjEyMzQ1fQ
        required: false
        description: Cursor for pagination (opaque string from previous response)
        name: cursor
        in: query
      - schema:
          type: integer
          exclusiveMinimum: 0
          description: Filter by institutional manager CIK
          example: 320193
        required: false
        description: Filter by institutional manager CIK
        name: managerCik
        in: query
      - schema:
          type: string
          maxLength: 500
          description: Search by manager name (partial match)
          example: Berkshire
        required: false
        description: Search by manager name (partial match)
        name: managerName
        in: query
      - schema:
          type: string
          minLength: 9
          maxLength: 9
          pattern: ^[A-Z0-9]{8}[0-9]$
          description: Filter by CUSIP to find all managers holding a specific security
          example: 037833100
        required: false
        description: Filter by CUSIP to find all managers holding a specific security
        name: cusip
        in: query
      - schema:
          type: integer
          exclusiveMinimum: 0
          description: Filter by company CIK to find institutional holders
          example: 320193
        required: false
        description: Filter by company CIK to find institutional holders
        name: companyCik
        in: query
      - schema:
          type: string
          minLength: 1
          maxLength: 10
          description: Filter by stock ticker to find institutional holders
          example: AAPL
        required: false
        description: Filter by stock ticker to find institutional holders
        name: ticker
        in: query
      - schema:
          type: string
          maxLength: 500
          description: Search by issuer name (partial match)
          example: Apple
        required: false
        description: Search by issuer name (partial match)
        name: issuerName
        in: query
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Filter by specific quarter end date (YYYY-MM-DD). E.g., 2024-09-30 for Q3 2024
          example: '2024-09-30'
        required: false
        description: Filter by specific quarter end date (YYYY-MM-DD). E.g., 2024-09-30 for Q3 2024
        name: reportPeriod
        in: query
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Filter filings on or after this date
          example: '2024-01-01'
        required: false
        description: Filter filings on or after this date
        name: startDate
        in: query
      - schema:
          type: string
          pattern: ^\d{4}-\d{2}-\d{2}$
          description: Filter filings on or before this date
          example: '2024-12-31'
        required: false
        description: Filter filings on or before this date
        name: endDate
        in: query
      - schema:
          type: number
          exclusiveMinimum: 0
          description: Minimum position value in USD
          example: 1000000000
        required: false
        description: Minimum position value in USD
        name: minValue
        in: query
      - schema:
          type: number
          exclusiveMinimum: 0
          description: Minimum number of shares
          example: 1000000
        required: false
        description: Minimum number of shares
        name: minShares
        in: query
      - schema:
          type: string
          enum:
          - put
          - call
          - equity
          description: 'Filter by position type: put options, call options, or equity only'
        required: false
        description: 'Filter by position type: put options, call options, or equity only'
        name: putCall
        in: query
      - schema:
          type: string
          maxLength: 500
          description: Search across manager name, issuer name, or ticker
          example: Berkshire Apple
        required: false
        description: Search across manager name, issuer name, or ticker
        name: q
        in: query
      responses:
        '200':
          description: Paginated list of institutional holdings
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per minute for this authentication path
              schema:
                type: string
                example: '15'
            X-RateLimit-Remaining:
              description: Remaining requests in the current minute window
              schema:
                type: string
                example: '14'
            X-RateLimit-Reset:
              description: Unix timestamp when the current minute window resets
              schema:
                type: string
                example: '1699012345'
            X-RateLimit-Monthly-Limit:
              description: Requests included for the account in a UTC calendar month
              schema:
                type: string
                example: '5000'
            X-RateLimit-Monthly-Remaining:
              description: Remaining requests in the account's current UTC calendar month
              schema:
                type: string
                example: '4999'
            X-RateLimit-Monthly-Reset:
              description: Unix timestamp when the next UTC calendar month begins
              schema:
                type: string
                example: '1785542400'
            X-RateLimit-Monthly-Policy:
              description: Monthly allowance policy. All current tiers use hard caps.
              schema:
                type: string
                enum:
                - hard
                example: hard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InstitutionalHoldingsResponse'
        '400':
          description: Invalid query parameters
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per minute for this authentication path
              schema:
                type: string
                example: '15'
            X-RateLimit-Remaining:
              description: Remaining requests in the current minute window
              schema:
                type: string
                example: '14'
            X-RateLimit-Reset:
              description: Unix timestamp when the current minute window resets
              schema:
                type: string
                example: '1699012345'
            X-RateLimit-Monthly-Limit:
              description: Requests included for the account in a UTC calendar month
              schema:
                type: string
                example: '5000'
            X-RateLimit-Monthly-Remaining:
              description: Remaining requests in the account's current UTC calendar month
              schema:
                type: string
                example: '4999'
            X-RateLimit-Monthly-Reset:
              description: Unix timestamp when the next UTC calendar month begins
              schema:
                type: string
                example: '1785542400'
            X-RateLimit-Monthly-Policy:
              description: Monthly allowance policy. All current tiers use hard caps.
              schema:
                type: string
                enum:
                - hard
                example: hard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized - API key required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Minute rate limit or tier monthly quota exceeded. Retry-After points to the relevant minute or monthly reset.
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per minute for this authentication path
              schema:
                type: string
                example: '15'
            X-RateLimit-Remaining:
              description: Remaining requests in the current minute window
              schema:
                type: string
                example: '14'
            X-RateLimit-Reset:
              description: Unix timestamp when the current minute window resets
              schema:
                type: string
                example: '1699012345'
            X-RateLimit-Monthly-Limit:
              description: Requests included for the account in a UTC calendar month
              schema:
                type: string
                example: '5000'
            X-RateLimit-Monthly-Remaining:
              description: Remaining requests in the account's current UTC calendar month
              schema:
                type: string
                example: '4999'
            X-RateLimit-Monthly-Reset:
              description: Unix timestamp when the next UTC calendar month begins
              schema:
                type: string
                example: '1785542400'
            X-RateLimit-Monthly-Policy:
              description: Monthly allowance policy. All current tiers use hard caps.
              schema:
                type: string
                enum:
                - hard
                example: hard
            X-RateLimit-Scope:
              description: Which limit caused this response
              schema:
                type: string
                enum:
                - minute
                - monthly
                example: minute
            Retry-After:
              description: Whole seconds for minute limits, or an HTTP-date for monthly limits
              schema:
                type: string
                example: '42'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: Internal server error
          headers:
            X-RateLimit-Limit:
              description: Maximum requests allowed per minute for this authentication path
              schema:
                type: string
                example: '15'
            X-RateLimit-Remaining:
              description: Remaining requests in the current minute window
              schema:
                type: string
                example: '14'
            X-RateLimit-Reset:
              description: Unix timestamp when the current minute window resets
              schema:
                type: string
                example: '1699012345'
            X-RateLimit-Monthly-Limit:
              description: Requests included for the account in a UTC calendar month
              schema:
                type: string
                example: '5000'
            X-RateLimit-Monthly-Remaining:
              description: Remaining requests in the account's current UTC calendar month
              schema:
                type: string
                example: '4999'
            X-RateLimit-Monthly-Reset:
              description: Unix timestamp when the next UTC calendar month begins
              schema:
                type: string
                example: '1785542400'
            X-RateLimit-Monthly-Policy:
              description: Monthly allowance policy. All current tiers use hard caps.
              schema:
                type: string
                enum:
                - hard
                example: hard
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      operationId: getApiV1InstitutionalHoldings
      x-operation-id-source: derived
components:
  schemas:
    InstitutionalHolding:
      type: object
      properties:
        cusip:
          type: string
          minLength: 9
          maxLength: 9
          pattern: ^[A-Z0-9]{8}[0-9]$
          description: 'CUSIP (Committee on Uniform Securities Identification Procedures) identifier.

            A 9-character alphanumeric code that uniquely identifies a security.

            - First 6 characters: Issuer identifier

            - Characters 7-8: Issue number

            - Character 9: Check digit (numeric)'
          example: 037833100
        issuerName:
          type: string
          description: Name of the issuing company as reported in the 13F
          example: APPLE INC
        classTitle:
          type: string
          description: Class/type of security (COM, CL A, SPONSORED ADR, etc.)
          example: COM
        companyCik:
          type:
          - integer
          - 'null'
          exclusiveMinimum: 0
          description: CIK of the issuing company (if resolved from CUSIP)
          example: 320193
        ticker:
          type:
          - string
          - 'null'
          description: Primary stock ticker (if resolved)
          example: AAPL
        value:
          type: integer
          description: Market value of the position in USD (as reported, typically in thousands)
          example: 69900000000
        shares:
          type: integer
          description: Number of shares held
          example: 400000000
        sharesType:
          type: string
          description: 'Type of shares:

            - **SH** = Shares (common)

            - **PRN** = Principal amount (for debt securities)'
          example: SH
        putCall:
          type:
          - string
          - 'null'
          description: 'Option type if this is an options position:

            - **Put** = Put option (right to sell)

            - **Call** = Call option (right to buy)

            - **null** = Common stock, not an option'
          example: null
        investmentDiscretion:
          type: string
          description: 'Type of investment discretion the manager has over the position:

            - **SOLE** = Manager has sole investment discretion

            - **DFND** = Investment discretion is defined (shared with others)

            - **OTHER** = Other arrangement'
          example: SOLE
        otherManager:
          type:
          - string
          - 'null'
          description: Name of other manager if investment discretion is shared
          example: null
        votingSole:
          type:
          - integer
          - 'null'
          description: Shares with sole voting authority
          example: 400000000
        votingShared:
          type:
          - integer
          - 'null'
          description: Shares with shared voting authority
          example: 0
        votingNone:
          type:
          - integer
          - 'null'
          description: Shares with no voting authority
          example: 0
        managerCik:
          type: integer
          exclusiveMinimum: 0
          description: CIK of the filing manager
          example: 320193
        managerName:
          type: string
          description: Name of the filing manager
        reportPeriodDate:
          type: string
          description: Quarter end date (YYYY-MM-DD)
        filedAt:
          type: string
          format: date-time
          description: 'SEC filing date. A calendar date encoded as midnight UTC: read only the date part (YYYY-MM-DD) and never convert it to a local time zone. For the moment the SEC accepted the filing, use acceptTs.'
          example: '2024-11-14T00:00:00.000Z'
        accessionNumber:
          type: string
          description: SEC accession number of the source filing
      required:
      - cusip
      - issuerName
      - classTitle
      - companyCik
      - ticker
      - value
      - shares
      - sharesType
      - putCall
      - investmentDiscretion
      - otherManager
      - votingSole
      - votingShared
      - votingNone
      - managerCik
      - managerName
      - reportPeriodDate
      - filedAt
      - accessionNumber
    InstitutionalHoldingsResponse:
      type: object
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/InstitutionalHolding'
        nextCursor:
          type:
          - string
          - 'null'
          description: Cursor for next page, null if no more pages
        hasMore:
          type: boolean
          description: Whether more items exist beyond this page
      required:
      - items
      - nextCursor
      - hasMore
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: Human-readable error message
          example: Invalid request parameters
        code:
          type: string
          description: Machine-readable error code
          example: VALIDATION_ERROR
        details:
          type: object
          additionalProperties: {}
          description: Additional error details (e.g., field-level validation errors)
      required:
      - error
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key sent as Bearer token in Authorization header.