earningscalls-dev Earnings API

openapi: 3.2.0
info:
  title: Call Transcripts Earnings API
  description: Access our growing archive of earnings call transcripts from publicly traded companies across 70+ countries and 175+ exchanges. Full-text search, speaker segments, and structured data.
  version: 1.0.0
  contact:
    name: API Support
    url: https://earningscalls.dev
servers:
- url: https://earningscalls.dev
  description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Earnings
  description: Earnings call listing and details
paths:
  /api/v1/earnings/latest:
    get:
      summary: Get Latest Earnings Calls
      tags:
      - Earnings
      description: Get the most recent earnings calls. Quick access to newest transcripts without pagination.
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 50
          default: 10
        in: query
        name: limit
        required: false
        description: Number of results (max 50)
      - schema:
          type: string
        in: query
        name: sector
        required: false
        description: Filter by sector
      responses:
        '200':
          description: Default Response
      operationId: getApiV1EarningsLatest
      x-operation-id-source: derived
  /api/v1/earnings/upcoming:
    get:
      summary: Get Upcoming Earnings Calls
      tags:
      - Earnings
      description: Get scheduled earnings calls that have not yet occurred. Combines data from earnings_calendar (upcoming) and earnings_calls (if any future entries exist). Upcoming rows carry no venue identity, so `mic` is rejected with 400 rather than silently ignored. Calendar rows resolve to an issuer by symbol where that mapping is unambiguous.
      parameters:
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        in: query
        name: limit
        required: false
        description: Number of results (max 100)
      - schema:
          type: integer
          minimum: 1
          maximum: 30
          default: 7
        in: query
        name: days
        required: false
        description: Days ahead to look (max 30)
      - schema:
          type: string
        in: query
        name: symbol
        required: false
        description: Filter by ticker symbol
      - schema:
          type: string
        in: query
        name: symbols
        required: false
        description: Comma-separated ticker symbols (max 100), exact case-insensitive match. Mutually exclusive with `symbol` and `issuer_id`/`issuer_ref`.
      - schema:
          type: string
        in: query
        name: issuer_id
        required: false
        description: Filter by issuer id (32-char hex, identical to `issuer_ref`) — resolved to the issuer's known listing and alias symbols. Mutually exclusive with `symbol` and `issuer_ref`.
      - schema:
          type: string
        in: query
        name: issuer_ref
        required: false
        description: Synonym of `issuer_id`. Mutually exclusive with `symbol` and `issuer_id`.
      - schema:
          type: string
          enum:
          - issuer
        in: query
        name: group_by
        required: false
        description: group_by=issuer appends a top-level `issuers` summary of the distinct companies among the returned rows.
      - schema:
          type: string
        in: query
        name: mic
        required: false
        description: NOT SUPPORTED on this endpoint — always rejected with 400 (upcoming rows carry no venue identity to filter on).
      responses:
        '200':
          description: Default Response
      operationId: getApiV1EarningsUpcoming
      x-operation-id-source: derived
  /api/v1/earnings/calendar:
    get:
      summary: Earnings Calendar (Date Range)
      tags:
      - Earnings
      description: 'Bulk earnings calendar over an arbitrary date range (max 92 days per request), paginated up to 500 rows per page. Supports multi-symbol and multi-issuer filters and `updated_since` for cheap delta syncs. Placeholder clock times are served as `event_time: null` plus a `session` hint (before_open / after_close / unknown) — never as a fake timestamp. Rows resolve to an issuer by symbol only when that mapping is unambiguous, and carry `call_id` once a matching earnings call exists in the archive. Calendar rows carry no venue identity (mic/exchange/country are not available on this endpoint).'
      parameters:
      - schema:
          type: string
          format: date
        in: query
        name: date_from
        required: true
        description: Start of the range (YYYY-MM-DD), inclusive.
      - schema:
          type: string
          format: date
        in: query
        name: date_to
        required: true
        description: End of the range (YYYY-MM-DD), inclusive. Max 92 days after date_from.
      - schema:
          type: integer
          minimum: 1
          default: 1
        in: query
        name: page
        required: false
        description: Page number
      - schema:
          type: integer
          minimum: 1
          maximum: 500
          default: 100
        in: query
        name: limit
        required: false
        description: Rows per page (max 500)
      - schema:
          type: string
        in: query
        name: symbols
        required: false
        description: Comma-separated ticker symbols (max 200), exact case-insensitive match. Mutually exclusive with issuer_ids.
      - schema:
          type: string
        in: query
        name: issuer_ids
        required: false
        description: Comma-separated issuer ids (32-char hex, the same values as `issuer_ref`; max 100). Each id resolves to the issuer's known listing and alias symbols. Unknown ids match nothing. Mutually exclusive with symbols.
      - schema:
          type: string
        in: query
        name: updated_since
        required: false
        description: ISO 8601 timestamp — only rows added or changed since then. Combine with your last pull time for delta syncs.
      responses:
        '200':
          description: Default Response
      operationId: getApiV1EarningsCalendar
      x-operation-id-source: derived
  /api/v1/earnings/:
    get:
      summary: List Earnings Calls
      tags:
      - Earnings
      description: List earnings calls with filtering, sorting, and pagination. Supports filtering by sector, industry, company, ticker, exchange, country, and date range. Symbol queries always include ambiguity metadata (`ambiguous`, `issuer_count`) because one bare symbol can belong to multiple unrelated companies (e.g. SAP = SAP SE, Saputo, Sappi).
      parameters:
      - schema:
          type: integer
          minimum: 1
          default: 1
        in: query
        name: page
        required: false
        description: Page number
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 20
        in: query
        name: limit
        required: false
        description: Results per page
      - schema:
          type: string
        in: query
        name: sector
        required: false
        description: Filter by sector
      - schema:
          type: string
        in: query
        name: industry
        required: false
        description: Filter by industry
      - schema:
          type: string
        in: query
        name: company
        required: false
        description: Filter by company name (partial match)
      - schema:
          type: string
        in: query
        name: ticker
        required: false
        description: Filter by company ticker (exact, case-insensitive; matches exchange-suffix variants like ALAB:US too). If no rows match, known cross-listing aliases resolve to the issuer's primary record (e.g. TSM returns the same issuer as 2330). Use strict=1 to disable both behaviors. The queried symbol is echoed on every item as `matched_alias`; `company_ticker`/`stock_symbol` always carry the stored value.
      - schema:
          type: string
        in: query
        name: exchange
        required: false
        description: Filter by exchange name, exact (e.g. NASDAQ, NYSE, NSEI). Use `mic` for the ISO-10383 form.
      - schema:
          type: string
        in: query
        name: mic
        required: false
        description: ISO 10383 Market Identifier Code (e.g. XNAS, XNYS, XNSE) — disambiguates symbol collisions across venues. Also matches rows whose stored exchange is blank when the issuer's primary listing carries the MIC (mirrors the served mic fill).
      - schema:
          type: string
        in: query
        name: country
        required: false
        description: Filter by ISO-3166 alpha-2 country code (e.g. US, IN, CA)
      - schema:
          type: string
          enum:
          - earnings
          - conference_presentation
          - shareholder_meeting
          - special
          - investor_day
          - trading_statement
          - m_and_a
          - guidance_update
          - operating_results
          - fixed_income
          - interim_update
        in: query
        name: event_type
        required: false
        description: Filter by event type (e.g. earnings, conference_presentation, shareholder_meeting, special, investor_day)
      - schema:
          type: string
          format: date
        in: query
        name: date_from
        required: false
        description: Events from this date (YYYY-MM-DD)
      - schema:
          type: string
          format: date
        in: query
        name: date_to
        required: false
        description: Events until this date (YYYY-MM-DD)
      - schema:
          type: string
          enum:
          - date_asc
          - date_desc
          - company_asc
          - company_desc
          default: date_desc
        in: query
        name: sort
        required: false
        description: Sort order
      - schema:
          type: string
        in: query
        name: issuer_id
        required: false
        description: Filter by issuer id (the `issuer_id` field on any item — 32-char hex, identical to `issuer_ref`). Returns all events for that company across every ticker format. Unknown ids return an empty result. Mutually exclusive with `ticker` and `issuer_ref`.
      - schema:
          type: string
        in: query
        name: issuer_ref
        required: false
        description: Synonym of `issuer_id` (the same 32-char hex id, kept for compatibility). Mutually exclusive with `ticker` and `issuer_id`.
      - schema:
          type: integer
          enum:
          - 0
          - 1
          default: 0
        in: query
        name: strict
        required: false
        description: strict=1 disables ticker-variant matching and the cross-listing alias fallback — only rows whose stored company_ticker or stock_symbol equals the query exactly are returned.
      - schema:
          type: string
          enum:
          - issuer
        in: query
        name: group_by
        required: false
        description: group_by=issuer appends a top-level `issuers` summary of the distinct companies, grouped by de-duplicated `issuer_ref`. With a `ticker`/`issuer_id`/`issuer_ref` filter the summary covers the FULL filtered result set; on unfiltered browse queries it covers the current page only. `data` and `pagination` are unchanged.
      - schema:
          type: integer
          enum:
          - 1
        in: query
        name: ambiguous
        required: false
        description: Accepted for symmetry — the ambiguity metadata (`ambiguous`, `issuer_count`) is always included on symbol and issuer queries and cannot be disabled.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                        company_name:
                          type: string
                        transcript_title:
                          type: string
                        event_type:
                          type: string
                        event_date_time:
                          type: string
                        sector:
                          type: string
                        industry:
                          type: string
                        market_cap:
                          type:
                          - number
                          - 'null'
                        stock_symbol:
                          type: string
                        company_ticker:
                          type: string
                          description: The STORED ticker of the row (may carry a venue suffix, e.g. 2330:TW). Never rewritten to the queried form — compare your query against `matched_alias` instead.
                        exchange:
                          type: string
                        mic:
                          type:
                          - string
                          - 'null'
                          description: ISO 10383 MIC derived from exchange (blank values are filled from the issuer's listing where known; null when unresolvable)
                        country:
                          type: string
                        currency:
                          type: string
                        fiscal_year:
                          type:
                          - integer
                          - 'null'
                          description: Fiscal year parsed from the call title (null when not present, e.g. non-earnings events)
                        fiscal_quarter:
                          type:
                          - integer
                          - 'null'
                          description: Fiscal quarter 1-4 parsed from the call title (null when not present)
                        issuer_id:
                          type:
                          - string
                          - 'null'
                          description: Stable issuer id (32-char hex, same value as `issuer_ref`) — one value per real company, identical on every listing/ticker format of that company. Null for a small share of legacy rows that cannot be resolved to an issuer.
                        issuer_ref:
                          type:
                          - string
                          - 'null'
                          description: Synonym of `issuer_id` (kept for compatibility). Null for unresolved legacy rows.
                        isin:
                          type:
                          - string
                          - 'null'
                          description: ISIN of the row's listing (falls back to the issuer's primary listing; null where unknown)
                        timezone:
                          type:
                          - string
                          - 'null'
                          description: IANA timezone of the issuer (null where unknown)
                        matched_alias:
                          type:
                          - string
                          - 'null'
                          description: Echo of the queried symbol (or the alias that resolved) — compare against your query for validation. Null on non-symbol queries.
                  pagination:
                    type: object
                    properties:
                      page:
                        type: integer
                      limit:
                        type: integer
                      total:
                        type: integer
                      total_pages:
                        type: integer
                  ambiguous:
                    type: boolean
                    description: True when the result set mixes two or more distinct companies (issuer_refs). Present on symbol and issuer queries.
                  issuer_count:
                    type: integer
                    description: Number of distinct resolved companies (issuer_refs) in the full result set. Present on symbol and issuer queries.
                  issuers:
                    type: array
                    description: 'Only with group_by=issuer: the distinct companies in the FULL filtered result set. Rows without a resolvable issuer are not listed as entries — they remain in `data` and the `pagination` total.'
                    items:
                      type: object
                      properties:
                        issuer_ref:
                          type:
                          - string
                          - 'null'
                        issuer_id:
                          type:
                          - string
                          - 'null'
                          description: Same 32-char hex id as `issuer_ref` (kept for envelope compatibility)
                        name:
                          type:
                          - string
                          - 'null'
                        primary_symbol:
                          type:
                          - string
                          - 'null'
                        exchange:
                          type:
                          - string
                          - 'null'
                          description: Display name of the issuer's primary listing venue
                        country:
                          type:
                          - string
                          - 'null'
                        count:
                          type: integer
      operationId: getApiV1Earnings
      x-operation-id-source: derived
  /api/v1/earnings/{id}:
    get:
      summary: Get Earnings Call Details
      tags:
      - Earnings
      description: 'Get full details of a specific earnings call including company info, transcript metadata, and speaker count. `id` is stable: a re-sourced call that replaces an existing call keeps its id; only genuinely new calls get new ids. `source_event_id` additionally carries an opaque internal event key (32-char hex) that stays identical when the same event is re-sourced.'
      parameters:
      - schema:
          type: integer
        in: path
        name: id
        required: true
        description: Earnings call ID
      responses:
        '200':
          description: Default Response
      operationId: getApiV1EarningsById
      x-operation-id-source: derived
components:
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key obtained from the dashboard after registration