api-ninjas-com Earnings API

openapi: 3.2.0
info:
  title: Ninjas Earnings 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
  description: The Earnings API provides comprehensive earnings report data for any company, including financial statements, balance sheets, cash flow statements, and key financial metrics. All data is sourced from official SEC filings (10-Q, 10-K).
paths:
  /v2/earnings:
    get:
      tags:
      - Earnings
      summary: Get earnings report data (returns an array; query by company or by filing date)
      description: Returns reported earnings results, filtered by `ticker`, `cik`, `year`, `quarter` or filing `date`. For dates of upcoming reports use /earningscalendar.
      operationId: getEarnings
      parameters:
      - $ref: '#/components/parameters/ticker'
      - $ref: '#/components/parameters/cik'
      - $ref: '#/components/parameters/period'
      - $ref: '#/components/parameters/quarter'
      - $ref: '#/components/parameters/year'
      - $ref: '#/components/parameters/date'
      - $ref: '#/components/parameters/date_start'
      - $ref: '#/components/parameters/date_end'
      - $ref: '#/components/parameters/offset'
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/EarningsResponse'
        '400':
          description: Bad Request
        '401':
          description: Unauthorized
        '500':
          description: Internal Server Error
      security:
      - ApiKeyAuth: []
components:
  parameters:
    offset:
      name: offset
      in: query
      required: false
      description: Number of results to skip for pagination. Results are returned 50 per page. Default is 0.
      schema:
        type: integer
        default: 0
        minimum: 0
    period:
      name: period
      in: query
      required: false
      description: Fiscal period (q1, q2, q3, q4, or fy). Requires a ticker/cik and year.
      schema:
        type: string
        enum:
        - q1
        - q2
        - q3
        - q4
        - fy
    year:
      name: year
      in: query
      required: false
      description: 'Fiscal year (e.g. 2024). With a ticker and no period/quarter, returns every period for that year; with period/quarter, one filing. Free accounts: current year only. Paid accounts: the last 5 fiscal years. Data older than 5 fiscal years requires a Business, Professional, or Enterprise subscription.'
      schema:
        type: integer
    date_end:
      name: date_end
      in: query
      required: false
      description: End of a filing-date range (YYYY-MM-DD). Combine with date_start to page through a window.
      schema:
        type: string
        format: date
    cik:
      name: cik
      in: query
      required: false
      description: Company Central Index Key (e.g., 796343). Alternative to ticker for identifying a company.
      schema:
        type: string
    quarter:
      name: quarter
      in: query
      required: false
      description: Fiscal quarter 1-4 (alternative to period). Requires ticker/cik and year.
      schema:
        type: integer
        minimum: 1
        maximum: 4
    ticker:
      name: ticker
      in: query
      required: false
      description: Company ticker symbol (e.g., ADBE). Use ticker or cik to query a company, or query by date with no ticker. 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
    date:
      name: date
      in: query
      required: false
      description: Return every filing whose SEC filing date equals this date (YYYY-MM-DD). Works with no ticker.
      schema:
        type: string
        format: date
    date_start:
      name: date_start
      in: query
      required: false
      description: 'Start of a filing-date range (YYYY-MM-DD): all companies that filed on/after this date.'
      schema:
        type: string
        format: date
  schemas:
    EarningsResponse:
      type: object
      properties:
        company_info:
          type: object
          properties:
            ticker:
              type: string
              example: ADBE
            cik:
              type: string
              example: '796343'
            fiscal_year:
              type: integer
              example: 2024
            company_name:
              type: string
              example: ADOBE INC.
            fiscal_quarter:
              type: integer
              example: 2
        income_statement:
          type: object
          properties:
            earnings_per_share_basic:
              type: number
              example: 3.5
            interest_expense:
              type: integer
              example: 41000000
            sales_and_marketing:
              type: integer
              example: 1445000000
            operating_income:
              type: integer
              example: 1885000000
            tax_provision:
              type: integer
              example: 357000000
            gross_profit:
              type: integer
              example: 4711000000
            earnings_per_share_diluted:
              type: number
              example: 3.49
            weighted_average_shares_basic:
              type: integer
              example: 449000000
            general_and_administrative:
              type: integer
              example: 355000000
            cost_of_revenue:
              type: integer
              example: 598000000
            stock_based_compensation:
              type:
              - number
              - 'null'
            total_revenue:
              type: integer
              example: 5309000000
            net_income:
              type: integer
              example: 1573000000
            net_income_available_to_common:
              type:
              - integer
              - 'null'
              example: 1573000000
            research_and_development:
              type:
              - integer
              - 'null'
              example: 984000000
            depreciation_and_amortization:
              type: integer
              example: 42000000
            weighted_average_shares_diluted:
              type: integer
              example: 451000000
        balance_sheet:
          type: object
          properties:
            goodwill:
              type: integer
              example: 12803000000
            retained_earnings:
              type: integer
              example: 35227000000
            total_assets:
              type: integer
              example: 30007000000
            current_liabilities:
              type: integer
              example: 9474000000
            total_debt:
              type:
              - number
              - 'null'
            total_liabilities:
              type: integer
              example: 15164000000
            long_term_debt:
              type: integer
              example: 4127000000
            accounts_receivable:
              type: integer
              example: 1612000000
            inventory:
              type:
              - number
              - 'null'
            current_assets:
              type: integer
              example: 11023000000
            property_plant_equipment:
              type: integer
              example: 1969000000
            intangible_assets:
              type: integer
              example: 933000000
            working_capital:
              type:
              - number
              - 'null'
            accounts_payable:
              type: integer
              example: 357000000
            stockholders_equity:
              type: integer
              example: 14843000000
            cash_and_equivalents:
              type: integer
              example: 7660000000
            temporary_equity:
              type:
              - number
              - 'null'
        cash_flow:
          type: object
          properties:
            share_repurchases:
              type: integer
              example: -4500000000
            operating_cash_flow:
              type: integer
              example: 3114000000
            net_cash_investing:
              type: integer
              example: 177000000
            net_cash_financing:
              type: integer
              example: -2770000000
            free_cash_flow:
              type:
              - number
              - 'null'
            capital_expenditures:
              type: integer
              example: -78000000
            dividends_paid:
              type:
              - number
              - 'null'
        filing_info:
          type: object
          properties:
            filing_type:
              type: string
              example: 10-Q
            filing_date:
              type: string
              example: '2024-06-26'
            period_end_date:
              type: string
              example: '2024-05-31'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-Api-Key
externalDocs:
  description: API Ninjas documentation
  url: https://api-ninjas.com/api