{"openapi":"3.0.3","info":{"title":"Earnings Call Transcripts API","description":"Access our growing archive of earnings call transcripts from US public companies. Full-text search, speaker segments, and structured data.","version":"1.0.0","contact":{"name":"API Support","url":"https://earningscalls.dev"}},"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key obtained from the dashboard after registration"}},"schemas":{}},"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"}}}},"/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).","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"}],"responses":{"200":{"description":"Default Response"}}}},"/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.","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)"},{"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."},{"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"}],"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","nullable":true},"stock_symbol":{"type":"string"},"company_ticker":{"type":"string"},"exchange":{"type":"string"},"mic":{"type":"string","nullable":true,"description":"ISO 10383 MIC derived from exchange (null when unmapped)"},"country":{"type":"string"},"currency":{"type":"string"},"fiscal_year":{"type":"integer","nullable":true,"description":"Fiscal year parsed from the call title (null when not present, e.g. non-earnings events)"},"fiscal_quarter":{"type":"integer","nullable":true,"description":"Fiscal quarter 1-4 parsed from the call title (null when not present)"}}}},"pagination":{"type":"object","properties":{"page":{"type":"integer"},"limit":{"type":"integer"},"total":{"type":"integer"},"total_pages":{"type":"integer"}}}}}}}}}}},"/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.","parameters":[{"schema":{"type":"integer"},"in":"path","name":"id","required":true,"description":"Earnings call ID"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/companies/":{"get":{"summary":"List Companies","tags":["Companies"],"description":"List all companies with earnings calls. Returns company metadata, call counts, and date range of available calls.","parameters":[{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false},{"schema":{"type":"string"},"in":"query","name":"search","required":false,"description":"Search by company name"},{"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":"exchange","required":false,"description":"Filter by exchange"},{"schema":{"type":"string","enum":["name_asc","name_desc","calls_desc","calls_asc"],"default":"name_asc"},"in":"query","name":"sort","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/companies/ticker/{ticker}":{"get":{"summary":"Get Company by Ticker","tags":["Companies"],"description":"Get company details and all earnings calls by stock ticker symbol. A bare symbol (e.g. `ALV`) returns every venue it is listed on; when that spans multiple companies the response includes a `venues` array. To pin one listing, pass a venue-suffixed ticker (e.g. `ALV:US`, `AIR:FR` — the exact value from any event's `company_ticker`), or use the `mic`/`exchange`/`country` filters.","parameters":[{"schema":{"type":"string"},"in":"query","name":"exchange","required":false,"description":"Filter by exchange name, exact (e.g. NASDAQ, 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, XNSE) — disambiguates symbol collisions across venues."},{"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"},"in":"path","name":"ticker","required":true,"description":"Stock ticker symbol (e.g., AAPL, MSFT)"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/companies/ticker/{ticker}/latest":{"get":{"summary":"Get Latest Call by Ticker","tags":["Companies"],"description":"Get the most recent earnings call for a specific stock ticker. Pass a venue-suffixed ticker (e.g. `ALV:US`) or use `mic`/`exchange`/`country` to disambiguate when the symbol is listed on multiple venues.","parameters":[{"schema":{"type":"string"},"in":"query","name":"exchange","required":false,"description":"Filter by exchange name, exact (e.g. NASDAQ, 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, XNSE) — disambiguates symbol collisions across venues."},{"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"},"in":"path","name":"ticker","required":true,"description":"Stock ticker symbol (e.g., AAPL, MSFT)"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/companies/{name}":{"get":{"summary":"Get Company by Name","tags":["Companies"],"description":"Get company details including all available earnings calls for that company.","parameters":[{"schema":{"type":"string"},"in":"path","name":"name","required":true,"description":"Company name (URL-encoded)"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/transcripts/recent":{"get":{"summary":"Recently Added Transcripts","tags":["Transcripts"],"description":"List transcripts in the order they landed in our database, newest first. Use cursor-based pagination (`since` and/or `after_id`) for stable polling. Returns metadata only — fetch full text via /api/v1/transcripts/:id. Available on the Free tier.","parameters":[{"schema":{"type":"string","format":"date-time"},"in":"query","name":"since","required":false,"description":"Only return transcripts added after this ISO 8601 timestamp (inclusive of microseconds, exclusive of the boundary)."},{"schema":{"type":"integer","minimum":1},"in":"query","name":"after_id","required":false,"description":"Cursor for sub-second stability — only return transcripts with earnings_call_id > this value (paired with the previous `next_after_id`)."},{"schema":{"type":"string","format":"date-time"},"in":"query","name":"event_since","required":false,"description":"Additionally filter by the earnings call event date — only return calls that happened on or after this ISO 8601 timestamp."},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/transcripts/{earningsId}":{"get":{"summary":"Get Full Transcript","tags":["Transcripts"],"description":"Get the complete transcript text for an earnings call. Pro/Enterprise plans only. Free tier returns 250-char preview.","parameters":[{"schema":{"type":"string","enum":["full","components","summary"],"default":"full"},"in":"query","name":"format","required":false,"description":"Response format"},{"schema":{"type":"integer"},"in":"path","name":"earningsId","required":true,"description":"Earnings call ID"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/transcripts/{earningsId}/summary":{"get":{"summary":"Get Transcript Summary","tags":["Transcripts"],"description":"Get a summary/preview of the transcript. Available on Free tier.","parameters":[{"schema":{"type":"integer"},"in":"path","name":"earningsId","required":true,"description":"Earnings call ID"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/transcripts/{earningsId}/components":{"get":{"summary":"Get Transcript Components","tags":["Transcripts"],"description":"Get structured transcript data including header info, call participants, and component sections.","parameters":[{"schema":{"type":"integer"},"in":"path","name":"earningsId","required":true,"description":"Earnings call ID"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/speakers/{earningsId}":{"get":{"summary":"Get Speaker Segments","tags":["Speakers"],"description":"Get all speaker segments (who said what) for an earnings call. Includes CEO, CFO, analysts, operator. Pro/Enterprise plans only.","parameters":[{"schema":{"type":"string","enum":["executive","analyst","operator","attendee","shareholder","unknown"]},"in":"query","name":"speaker_type","required":false,"description":"Filter by speaker role (executive, analyst, operator, attendee, shareholder)."},{"schema":{"type":"string"},"in":"query","name":"speaker_name","required":false,"description":"Filter by speaker name (partial match)"},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":200,"default":50},"in":"query","name":"limit","required":false},{"schema":{"type":"integer"},"in":"path","name":"earningsId","required":true,"description":"Earnings call ID"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/search/":{"get":{"summary":"Full-Text Search","tags":["Search"],"description":"Search across 17K+ earnings calls. Supports Google-style operators in the q parameter: \"exact phrase\" for phrase match, AND/OR for boolean, -word for negation. Example: q=guidance OR outlook -macro. Returns transcripts, speaker segments, or company names. Pro/Enterprise only.","parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":true,"description":"Search query. Supports \"exact phrase\", word AND word, word OR word, -word (negation)."},{"schema":{"type":"string","enum":["all","transcripts","speakers","companies"],"default":"all"},"in":"query","name":"type","required":false,"description":"Search scope"},{"schema":{"type":"string"},"in":"query","name":"speaker_type","required":false,"description":"When type=speakers: filter to a specific speaker role (executive, analyst, operator, attendee, shareholder, unknown)."},{"schema":{"type":"string"},"in":"query","name":"ticker","required":false,"description":"Filter results to a specific ticker (case-insensitive). Applies to transcripts and speakers scopes."},{"schema":{"type":"string"},"in":"query","name":"sector","required":false,"description":"Filter results by sector"},{"schema":{"type":"string"},"in":"query","name":"industry","required":false,"description":"Filter results by industry"},{"schema":{"type":"string","format":"date"},"in":"query","name":"date_from","required":false,"description":"Filter from date"},{"schema":{"type":"string","format":"date"},"in":"query","name":"date_to","required":false,"description":"Filter to date"},{"schema":{"type":"integer","minimum":1,"default":1},"in":"query","name":"page","required":false},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/search/by_ticker":{"get":{"summary":"Aggregate Search by Ticker","tags":["Search"],"description":"Search transcripts and return per-ticker aggregated counts (how many of a ticker's calls in the window mentioned the query). Optional ticker filter lets you scope to a known universe (e.g. Fortune 500). The `results` leaderboard is capped at `limit` (max 500), but `total_companies` and `total_calls` always reflect the full matching set independent of limit. Pro/Enterprise only.","parameters":[{"schema":{"type":"string"},"in":"query","name":"q","required":true,"description":"Search query (required, 2+ chars)"},{"schema":{"type":"string"},"in":"query","name":"tickers","required":false,"description":"Comma-separated ticker list to scope the search (e.g. NVDA,MSFT,AAPL). Omit to scan all."},{"schema":{"type":"string"},"in":"query","name":"sector","required":false,"description":"Filter by GICS sector"},{"schema":{"type":"string"},"in":"query","name":"industry","required":false,"description":"Filter by industry"},{"schema":{"type":"string","format":"date"},"in":"query","name":"date_from","required":false,"description":"YYYY-MM-DD lower bound"},{"schema":{"type":"string","format":"date"},"in":"query","name":"date_to","required":false,"description":"YYYY-MM-DD upper bound"},{"schema":{"type":"integer","minimum":1,"maximum":500,"default":500},"in":"query","name":"limit","required":false}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/sectors":{"get":{"summary":"List Sectors","tags":["Metadata"],"description":"Get all 11 GICS sectors with company and call counts. Useful for filtering and aggregation.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object","properties":{"sector":{"type":"string"},"company_count":{"type":"integer"},"call_count":{"type":"integer"}}}}}}}}}}}},"/api/v1/industries":{"get":{"summary":"List Industries","tags":["Metadata"],"description":"Get all 100+ industries, optionally filtered by sector. Includes company and call counts.","parameters":[{"schema":{"type":"string"},"in":"query","name":"sector","required":false,"description":"Filter by sector"}],"responses":{"200":{"description":"Default Response"}}}},"/api/v1/stats":{"get":{"summary":"Database Statistics","tags":["Metadata"],"description":"Get total counts for earnings calls, transcripts, speakers, companies, and date range coverage.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/me":{"get":{"summary":"Authenticated User Info","tags":["Metadata"],"description":"Get information about the authenticated API key: tier, monthly request usage, and limits. Primarily used by the MCP server to verify a paid subscription is active.","responses":{"200":{"description":"Default Response"}}}},"/api/v1/event-types":{"get":{"summary":"List Event Types","tags":["Metadata"],"description":"Get all earnings call event types (e.g., Earnings Calls, Shareholder Meetings, Guidance Calls).","responses":{"200":{"description":"Default Response"}}}},"/api/v1/exchanges":{"get":{"summary":"List Exchanges","tags":["Metadata"],"description":"Get all stock exchanges (NYSE, NASDAQ, etc.) with company and call counts.","responses":{"200":{"description":"Default Response"}}}}},"servers":[{"url":"https://earningscalls.dev","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"tags":[{"name":"Earnings","description":"Earnings call listing and details"},{"name":"Companies","description":"Company search and details"},{"name":"Transcripts","description":"Full transcript text (Pro/Enterprise)"},{"name":"Speakers","description":"Speaker segments and analysis (Pro/Enterprise)"},{"name":"Search","description":"Full-text search (Pro/Enterprise)"},{"name":"Metadata","description":"Sectors, industries, exchanges, and database stats"}]}