Earnings Feed Account API

openapi: 3.2.0
info:
  title: Earnings Feed Account 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: Account
  description: Retrieve information about the authenticated user's account.
paths:
  /api/v1/me:
    get:
      tags:
      - Account
      summary: Get current user
      description: Returns information about the authenticated user. Useful for verifying API key ownership and for integration connection labels (e.g. Zapier).
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Authenticated user info
          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/MeResponse'
        '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: getApiV1Me
      x-operation-id-source: derived
components:
  schemas:
    MeResponse:
      type: object
      properties:
        email:
          type: string
          format: email
          description: Account email address
          example: user@example.com
        name:
          type:
          - string
          - 'null'
          description: Full name (first + last), or null if not set
          example: Jane Smith
        plan:
          type: string
          description: Subscription tier
          example: free
      required:
      - email
      - name
      - plan
    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.