api-ninjas-com Earnings Calendar API

openapi: 3.2.0
info:
  title: Ninjas Earnings Calendar 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: Earnings Calendar
  description: The Earnings Calendar API provides access to earnings results and upcoming earning dates for all major companies.
paths:
  /v1/earningscalendar:
    get:
      tags:
      - Earnings Calendar
      summary: Get earnings results and upcoming dates
      description: 'Returns earnings reports for one company (`ticker`), one calendar date (`date`), or a date range (`date_start`/`date_end`). At least one of these is required, and `date` cannot be combined with a range. Covers 50,000+ tickers on US and international exchanges with history back to 2000. How far back a request can reach depends on the plan: Free returns the last 12 months, Developer the last 5 years, and Business and Professional the full history. A `date` or range that starts before the plan''s window returns an error; `ticker` lookups return only the reports inside it. Results are sorted by date (newest first) and returned 50 per request; use `offset` (premium) to page. Past reports only by default; set `show_upcoming=true` (premium) to include scheduled future reports. EPS and revenue are in the company''s reporting currency. `actual_eps`/`estimated_eps` are on the adjusted (non-GAAP) basis analysts use; `actual_eps_gaap` is GAAP diluted EPS from the SEC 10-Q/10-K (US SEC filers). For upcoming dates filtered by exchange use /upcomingearnings.'
      operationId: getEarningsCalendar
      parameters:
      - name: ticker
        in: query
        required: false
        schema:
          type: string
        description: Company ticker symbol (e.g. MSFT, 7203.T). Returns that company's earnings reports, newest first. 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. Non-US stocks take an exchange suffix (SHEL.L, 7203.T) or prefix (LON:SHEL).
      - name: date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Single report date in YYYY-MM-DD format (e.g. 2026-07-30). Returns every company reporting on that date. Cannot be combined with date_start or date_end.
      - name: date_start
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Start of a report-date range (YYYY-MM-DD, inclusive). If date_end is omitted, the range ends 7 days after date_start.
      - name: date_end
        in: query
        required: false
        schema:
          type: string
          format: date
        description: End of a report-date range (YYYY-MM-DD, inclusive). Must be on or after date_start. If date_start is omitted, the range starts 7 days before date_end.
      - name: show_upcoming
        in: query
        required: false
        schema:
          type: boolean
          default: false
        description: 'Include scheduled future reports (dates after today). Without it only past and same-day reports are returned. Premium only: free-tier requests that pass this parameter are rejected.'
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of results to skip, for pagination. Each request returns up to 50 results, so use offset=50, 100, ... to page. Premium only.
      responses:
        '200':
          $ref: '#/components/responses/EarningsCalendarOpenapi_200'
        '400':
          $ref: '#/components/responses/EarningsCalendarOpenapi_400'
        '401':
          $ref: '#/components/responses/EarningsCalendarOpenapi_401'
        '500':
          $ref: '#/components/responses/EarningsCalendarOpenapi_500'
      security:
      - ApiKeyAuth: []
  /v1/earningscalendarlist:
    get:
      tags:
      - Earnings Calendar
      summary: Get a list of all available companies in the earnings calendar
      description: Returns the list of companies covered by the earnings calendar. For a specific company's earnings results and reporting dates use /earningscalendar.
      operationId: getEarningsCalendarList
      parameters: []
      responses:
        '200':
          description: A list of all available companies
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EarningsCalendarListResponse'
        '400':
          $ref: '#/components/responses/EarningsCalendarOpenapi_400'
        '401':
          $ref: '#/components/responses/EarningsCalendarOpenapi_401'
        '500':
          $ref: '#/components/responses/EarningsCalendarOpenapi_500'
      security:
      - ApiKeyAuth: []
  /v1/upcomingearnings:
    get:
      tags:
      - Earnings Calendar
      summary: Get upcoming earnings dates with filtering
      operationId: getUpcomingEarnings
      description: Returns a list of upcoming earnings dates with filtering capabilities. You can filter by date range, single date, exchange, or ticker symbol. Results are limited to dates from today onwards. Premium only.
      parameters:
      - name: start_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Start date in YYYY-MM-DD format. Must be today or later. Defaults to today if not provided.
      - name: end_date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: End date in YYYY-MM-DD format. Must be after start_date. Defaults to 10 years from today if not provided.
      - name: date
        in: query
        required: false
        schema:
          type: string
          format: date
        description: Single date in YYYY-MM-DD format. If provided, overrides start_date and end_date to filter by this exact date.
      - name: exchange
        in: query
        required: false
        schema:
          type: string
        description: Exchange code to filter by (e.g., NASDAQ, NYSE, HKSE, LSE, TSX). Returns only earnings from companies listed on the specified exchange.
      - name: ticker
        in: query
        required: false
        schema:
          type: string
        description: Ticker symbol to filter by (e.g., AAPL, 0700.HK). Returns only earnings for that specific company. 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. Non-US stocks take an exchange suffix (SHEL.L, 7203.T) or prefix (LON:SHEL).
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 100
        description: Maximum number of results to return. Must be between 1 and 100 (inclusive). Default is 100.
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
        description: Number of results to skip for pagination. Must be a non-negative integer. Use in combination with limit to paginate through results.
      responses:
        '200':
          description: A list of upcoming earnings
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UpcomingEarningsResponse'
        '400':
          $ref: '#/components/responses/EarningsCalendarOpenapi_400'
        '401':
          $ref: '#/components/responses/EarningsCalendarOpenapi_401'
        '500':
          $ref: '#/components/responses/EarningsCalendarOpenapi_500'
      security:
      - ApiKeyAuth: []
components:
  responses:
    EarningsCalendarOpenapi_500:
      description: Internal Server Error
    EarningsCalendarOpenapi_400:
      description: Bad Request
    EarningsCalendarOpenapi_401:
      description: Unauthorized
    EarningsCalendarOpenapi_200:
      description: A list of earnings results
      content:
        application/json:
          schema:
            type: array
            items:
              $ref: '#/components/schemas/EarningsResult'
  schemas:
    EarningsResult:
      type: object
      properties:
        date:
          type: string
          format: date
          description: The date of the earnings.
        ticker:
          type: string
          description: The ticker symbol of the company.
        fiscal_year:
          type:
          - integer
          - 'null'
          description: The company's fiscal year for this earnings report. Sourced from the earnings call transcript, with a fallback to the SEC 10-Q filing.
        fiscal_quarter:
          type:
          - integer
          - 'null'
          description: The company's fiscal quarter (1-4) for this earnings report. Sourced from the earnings call transcript, with a fallback to the SEC 10-Q filing.
        period_end_date:
          type:
          - string
          - 'null'
          format: date
          description: Last day of the fiscal period covered by this report, from the SEC 10-Q/10-K. Premium only.
        earnings_timing:
          type:
          - string
          - 'null'
          enum:
          - before_market
          - after_market
          - null
          description: 'When the company released this report relative to U.S. market hours: before_market (before the 9:30 a.m. ET open) or after_market (after the 4:00 p.m. ET close). Set for each report on its own, verified against the company''s SEC 8-K earnings filing where it has one; omitted when unknown. Premium only — free tier users receive a placeholder upgrade message string in place of the enum value.'
        earnings_call_timestamp:
          type:
          - integer
          - 'null'
          description: Unix timestamp of when the earnings call occurred or is scheduled to occur. Premium only — free tier users receive a placeholder upgrade message string in place of the integer.
        actual_revenue:
          type:
          - number
          - 'null'
          description: Actual revenue for the reported period, in the company's reporting currency.
        estimated_revenue:
          type:
          - number
          - 'null'
          description: 'Consensus revenue estimate, in the company''s reporting currency. Premium only: free-tier users receive a placeholder upgrade message string in place of the value.'
        actual_eps:
          type:
          - number
          - 'null'
          description: Actual earnings per share on the adjusted (non-GAAP) basis that analyst estimates use, in the company's reporting currency. See actual_eps_gaap for GAAP diluted EPS.
        actual_eps_gaap:
          type:
          - number
          - 'null'
          description: 'GAAP diluted EPS from the SEC 10-Q (or 10-K for the fourth quarter), rounded to 2 decimals. Available for US SEC filers once the filing is published, which is usually the report day and at most ~100 days later. Fourth-quarter values are derived from the annual 10-K and can differ from the company-reported Q4 figure by a few cents. Premium only: free-tier users receive a placeholder upgrade message string in place of the value.'
        estimated_eps:
          type:
          - number
          - 'null'
          description: 'Consensus EPS estimate (adjusted basis), in the company''s reporting currency. Premium only: free-tier users receive a placeholder upgrade message string in place of the value.'
        revenue_difference:
          type:
          - number
          - 'null'
          description: 'Actual minus estimated revenue, in the reporting currency. Premium only: free-tier users receive a placeholder upgrade message string in place of the value.'
        revenue_difference_pct:
          type:
          - number
          - 'null'
          description: Revenue surprise as a percent of the estimate. Premium only — free tier users receive a placeholder upgrade message string.
        eps_difference:
          type:
          - number
          - 'null'
          description: 'Actual minus estimated EPS (adjusted basis). Premium only: free-tier users receive a placeholder upgrade message string in place of the value.'
        eps_difference_pct:
          type:
          - number
          - 'null'
          description: EPS surprise as a percent of the estimate. Premium only — free tier users receive a placeholder upgrade message string.
        sec_filing_type:
          type:
          - string
          - 'null'
          description: 'SEC filing that actual_eps_gaap comes from: "10-Q", or "10-K (Q4 derived from annual)" for fourth quarters. Premium only: free-tier users receive a placeholder upgrade message string in place of the value.'
        sec_filing_date:
          type:
          - string
          - 'null'
          format: date
          description: 'Date the SEC filing behind actual_eps_gaap was filed. Premium only: free-tier users receive a placeholder upgrade message string in place of the value.'
        report_date_status:
          type:
          - string
          - 'null'
          enum:
          - confirmed
          - projected
          - null
          description: '''confirmed'' once the company''s SEC 8-K Item 2.02 earnings release for this report has been matched, otherwise ''projected''. Business tier and above only — lower tiers receive a placeholder upgrade message string.'
        date_confirmed:
          type:
          - boolean
          - 'null'
          description: True when an SEC 8-K Item 2.02 (Results of Operations) filing has been matched to this report. Business tier and above only — lower tiers receive a placeholder upgrade message string.
        report_datetime:
          type:
          - string
          - 'null'
          description: Time the SEC accepted the company's 8-K Item 2.02 earnings filing, in ISO 8601 U.S. Eastern time (e.g. 2026-07-30T16:30:28-04:00). Companies usually file within minutes of releasing results. Business tier and above.
        sec_8k_url:
          type:
          - string
          - 'null'
          description: URL of the SEC 8-K Item 2.02 filing that confirmed this report. Business tier and above.
        eps_beat_miss:
          type:
          - string
          - 'null'
          enum:
          - beat
          - miss
          - inline
          - null
          description: Whether actual EPS beat, missed, or matched the estimate. Business tier and above.
        revenue_beat_miss:
          type:
          - string
          - 'null'
          enum:
          - beat
          - miss
          - inline
          - null
          description: Whether actual revenue beat, missed, or matched the estimate. Business tier and above.
        eps_surprise_streak:
          type:
          - integer
          - 'null'
          description: Number of consecutive most-recent quarters the company beat its EPS estimate (0 if the latest report missed). Business tier and above only — lower tiers receive a placeholder upgrade message string.
        avg_eps_surprise_pct_4q:
          type:
          - number
          - 'null'
          description: Average EPS surprise percent over the last 4 reported quarters. Business tier and above only — lower tiers receive a placeholder upgrade message string.
        eps_sue:
          type:
          - number
          - 'null'
          description: 'Standardized Unexpected Earnings: the latest EPS surprise divided by the standard deviation of recent surprises (a normalized surprise magnitude used in post-earnings-drift strategies). Business tier and above only — lower tiers receive a placeholder upgrade message string.'
        year_ago_date:
          type:
          - string
          - 'null'
          format: date
          description: 'Report date of the same quarter one year earlier (the report 330-400 days before this one, closest to 52 weeks). Business tier and above only: lower tiers receive a placeholder upgrade message string.'
        year_ago_actual_eps:
          type:
          - number
          - 'null'
          description: 'Actual EPS (adjusted basis) reported one year earlier. Business tier and above only: lower tiers receive a placeholder upgrade message string.'
        year_ago_actual_revenue:
          type:
          - number
          - 'null'
          description: 'Actual revenue reported one year earlier, in the reporting currency. Business tier and above only: lower tiers receive a placeholder upgrade message string.'
        eps_growth_yoy_pct:
          type:
          - number
          - 'null'
          description: 'Year-over-year EPS growth in percent: (actual_eps - year_ago_actual_eps) / |year_ago_actual_eps| x 100, so a narrowing loss is positive growth. Business tier and above.'
        revenue_growth_yoy_pct:
          type:
          - number
          - 'null'
          description: Year-over-year revenue growth in percent. Business tier and above.
        last_earnings_move_pct:
          type:
          - number
          - 'null'
          description: One-day percent price reaction to this earnings report, computed timing-aware (next session for after-market reports). Business tier and above.
        avg_earnings_move_pct:
          type:
          - number
          - 'null'
          description: Average absolute one-day price move over the company's last 4 reported earnings, each measured from that report's own release session. Business tier and above.
        price_reaction:
          type:
          - object
          - 'null'
          description: Stock price reaction to this report, from daily bars. The reaction session is the report date for before-market and during-market reports (and when timing is unknown), and the next trading day for after-market reports. Business tier and above.
          properties:
            reaction_date:
              type: string
              format: date
              description: First trading session that reflects the report.
            pre_earnings_close:
              type: number
              description: Close of the last session before the reaction session.
            gap_pct:
              type:
              - number
              - 'null'
              description: Reaction-session open vs pre_earnings_close, in percent.
            move_1d_pct:
              type:
              - number
              - 'null'
              description: Reaction-session close vs pre_earnings_close, in percent.
            move_3d_pct:
              type:
              - number
              - 'null'
              description: Close of the 3rd session (counting the reaction session as 1) vs pre_earnings_close, in percent.
            move_5d_pct:
              type:
              - number
              - 'null'
              description: Close of the 5th session vs pre_earnings_close, in percent.
            pre_earnings_move_5d_pct:
              type:
              - number
              - 'null'
              description: pre_earnings_close vs the close 5 sessions earlier, in percent (the run-up into the report).
            volume_ratio:
              type:
              - number
              - 'null'
              description: Reaction-session volume divided by the average volume of the 20 sessions up to the pre-earnings session.
        days_to_next_earnings:
          type:
          - integer
          - 'null'
          description: Calendar days from today until the company's next scheduled earnings date. Business tier and above only — lower tiers receive a placeholder upgrade message string.
        next_earnings_date:
          type:
          - string
          - 'null'
          format: date
          description: The company's next scheduled earnings date. Business tier and above only — lower tiers receive a placeholder upgrade message string.
        has_transcript:
          type:
          - boolean
          - 'null'
          description: Whether an earnings call transcript is available for this report (retrievable via /v1/earningstranscript). Business tier and above only — lower tiers receive a placeholder upgrade message string.
        surprise_history:
          type:
          - array
          - 'null'
          description: Up to the 4 most-recent reported quarters, most-recent first. Business tier and above only — lower tiers receive a placeholder upgrade message string.
          items:
            type: object
            properties:
              date:
                type: string
                format: date
                description: Report date.
              actual_eps:
                type:
                - number
                - 'null'
                description: Actual EPS.
              estimated_eps:
                type:
                - number
                - 'null'
                description: Estimated (consensus) EPS.
              eps_surprise_pct:
                type:
                - number
                - 'null'
                description: EPS surprise as a percent of the estimate.
    EarningsCalendarListResponse:
      type: array
      items:
        type: object
        properties:
          ticker:
            type: string
            description: The company ticker symbol.
          company:
            type: string
            description: The company name.
    UpcomingEarningsResult:
      type: object
      properties:
        ticker:
          type: string
          description: The ticker symbol of the company.
        date:
          type: string
          format: date
          description: The date of the upcoming earnings.
        eps_estimated:
          type:
          - number
          - 'null'
          description: The estimated earnings per share in USD.
        revenue_estimated:
          type:
          - number
          - 'null'
          description: The estimated revenue in USD.
        exchange:
          type: string
          description: The exchange code where the company is listed.
        earnings_timing:
          type:
          - string
          - 'null'
          enum:
          - before_market
          - after_market
          - null
          description: The session the company is expected to release this report in (before_market or after_market), the same value /v1/earningscalendar returns for it; omitted when unknown.
    UpcomingEarningsResponse:
      type: array
      items:
        $ref: '#/components/schemas/UpcomingEarningsResult'
      description: Array of upcoming earnings objects.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api