Getting started · Introduction

EarningsDeck API

Structured public-company data for financial products, research workflows, and investor tools.

EarningsDeck brings company profiles, financial statements, regulatory filings, insider transactions, earnings results, and investor events into one predictable API. The platform is designed for developers who need traceable company intelligence without building and maintaining a separate parser for every source.

Every response uses consistent field names, ISO-formatted dates, explicit currencies, and source references where available. Records are normalized for programmatic use while preserving the identifiers needed to verify them against the original company or regulatory source.

What you can access

Company profiles. Ticker, legal name, CIK, exchange, industry, fiscal calendar, and market metadata.
Financial statements. Normalized income statements, balance sheets, cash-flow statements, and key reported metrics.
SEC filings. 10-K, 10-Q, 8-K, Form 4, proxy statements, accession numbers, and source documents.
Insider transactions. Reported purchases, sales, grants, transaction codes, ownership types, and post-transaction holdings.
Earnings data. Reporting dates, market sessions, reported results, estimates, surprise values, and supporting materials.
Investor events. Earnings calls, investor days, conferences, dividend events, and webcast information.

Data conventions

JSON responses use snake_case field names. Dates are returned as YYYY-MM-DD; timestamps use ISO 8601 UTC. Monetary fields include a currency value or inherit the currency declared on the containing statement. Missing data is returned as null, never as an empty string or zero.

Source-first data

Where possible, records include filing URLs, accession numbers, source documents, or company-hosted materials so your application can preserve a verifiable research trail.

Coverage

EarningsDeck tracks public-company and investor-relations records across supported markets. Coverage varies by company, security type, reporting jurisdiction, and the history available from original sources. Each endpoint documents its relevant update cadence and coverage constraints.

Built for

Portfolio and watchlist applications.
Financial research and screening tools.
Earnings calendars and alerting systems.
Investor-relations monitoring workflows.
Internal company-data services.

Design principles

Predictable

Consistent authentication, pagination, errors, and field naming across endpoints.

Traceable

Source metadata remains attached to the normalized record wherever available.

Typed

Dates, numbers, booleans, and null values have stable machine-readable meanings.

Focused

The API exposes company intelligence without unrelated market commentary.

Getting started · Quickstart

Make your first request.

Create a key, authenticate, and retrieve a public-company record in a few minutes.

Create an account

API access is available on Pro and Enterprise. Create an account, select a plan, and open Dashboard → API Keys.

Generate an API key

Give the key a recognizable name such as local-development. The complete secret is displayed once; copy it into a secure environment variable.

EARNINGSDECK_API_KEY=ed_live_your_api_key

Send the key in the header

Include x-api-key on every API request. Do not send the key as a query parameter.

Request a company

Retrieve Apple's normalized company profile using the language of your choice.

Handle the response

A successful request returns JSON with a 200 status. Inspect non-2xx responses for a stable error code and human-readable message.

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/companies?ticker=AAPL" \ --header "x-api-key: ed_live_your_api_key"

const response = await fetch( "https://earningsdeck.xyz/api/v1/companies?ticker=AAPL", { headers: { "x-api-key": process.env.EARNINGSDECK_API_KEY } } ); const data = await response.json(); console.log(data.company.name);

import os import requests response = requests.get( "https://earningsdeck.xyz/api/v1/companies", params={"ticker": "AAPL"}, headers={"x-api-key": os.environ["EARNINGSDECK_API_KEY"]}, ) print(response.json()["company"]["name"])

Next step

Once the company request works, use the same header with /api/v1/financials, /api/v1/filings, or another endpoint in the API reference.

Getting started · Authentication

Authenticate every request.

EarningsDeck uses API keys sent through the x-api-key request header.

Generate a key

Open Dashboard → API Keys. Create a key for each environment or integration so individual credentials can be revoked without disrupting other applications.

Send the key

Add x-api-key: ed_live_your_api_key to every request. Keys in query strings may be recorded in URLs and are not supported.

Protect the key

Store keys in environment variables or a secrets manager. Never expose a production key in browser code, public repositories, screenshots, or support messages.

Authenticated cURL request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/financials?ticker=AAPL&period=quarterly&limit=4" \ --header "x-api-key: ed_live_your_api_key"

Key lifecycle

Use separate keys for development and production.
Name keys by application or environment.
Revoke a key immediately if it may have been exposed.
Rotate long-lived credentials as part of normal security maintenance.
Removing a key invalidates it immediately and cannot be undone.

Authentication errors

A missing, malformed, invalid, or revoked key returns 401 Unauthorized. A valid key attempting to use an unavailable product capability returns 403 Forbidden.

{ "error": { "code": "invalid_api_key", "message": "The supplied API key is missing, invalid, or revoked." } }

Getting started · Rate limits

Limits are applied per account.

Daily request allowances protect platform reliability and reset at 00:00 UTC.

Every API request counts toward the daily allowance, including requests that return validation or not-found errors. Requests rejected before authentication do not consume quota.

Plan	API access	Daily limit	Redistribution	Limit behavior
Free $0	No	—	No	API key creation unavailable
Pro $9.99/month	Yes	500 requests	No	Returns 429 after daily limit
Enterprise $99/month	Yes	Unlimited*	Yes	Fair-use protections apply

*Enterprise access is operationally unlimited for normal production use. Abuse-prevention and infrastructure-protection controls still apply.

Rate-limit headers

Successful authenticated responses include the current limit, remaining allowance, and Unix timestamp at which the quota resets.

When the limit is exceeded

The API returns 429 Too Many Requests. Wait until reset_at before retrying. Repeated retries do not extend the reset time, but applications should stop automatically rather than continuing to send requests.

{ "error": { "code": "rate_limit_exceeded", "message": "Your daily request limit has been reached.", "reset_at": "2026-07-24T00:00:00Z" } }

Recommended behavior

Track x-ratelimit-remaining, cache stable responses, and avoid polling endpoints whose underlying data changes infrequently.

API reference · Companies

Companies

Retrieve a single company profile.

GET/api/v1/companies/{ticker}

Returns the normalized profile for one company. The ticker is a path segment, not a query parameter. To list every covered company use GET /api/v1/companies, which takes no parameters and returns all active tickers with their earnings-material counts.

Query parameters

Parameter	Type	Required	Description
`ticker`	string (path)	Required	Ticker symbol, case-insensitive. Example: AAPL.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/companies/AAPL" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "ticker": "AAPL", "name": "Apple Inc.", "exchange": "NASDAQ", "cik": "0000320193", "sector": "Technology", "country": "US", "ir_url": "https://investor.apple.com" }

Error responses

404 Not Found

{ "error": "Company not found" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

The profile exposes ir_url (the company's investor-relations page). There is no website field on this response.

API reference · Financials

Financials

Income statements, balance sheets, and cash-flow statements.

GET/api/v1/financials

Returns normalized financial statements grouped into three arrays. All monetary values are reported in millions of the stated currency — read the unit field rather than assuming raw dollars.

Query parameters

Parameter	Type	Required	Description
`ticker`	string	Required	Ticker symbol. Example: AAPL.
`period`	string	Optional	annual, quarterly, or an exact label such as "FY 2025". Defaults to all periods.
`limit`	integer	Optional	Maximum statements per array. Default 10, maximum 100.
`period_type`	string	Optional	Legacy alias for period. Still accepted for backwards compatibility.
`form_type`	string	Optional	Filter by originating filing form, e.g. 10-K or 10-Q.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/financials?ticker=AAPL&period=annual&limit=4" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "ticker": "AAPL", "company": "Apple Inc.", "currency": "USD", "unit": "millions", "count": 4, "financials": { "income_statements": [ { "ticker": "AAPL", "period": "FY 2025", "report_period": null, "filing_date": "2025-10-31", "form_type": "10-K", "revenue": 416161, "cost_of_revenue": 210352, "gross_profit": 205809, "operating_income": 133000, "ebit": 133000, "net_income": 112010, "earnings_per_share_diluted": 7.46, "net_margin": 0.2692 } ], "balance_sheets": [ { "ticker": "AAPL", "period": "FY 2025", "form_type": "10-K", "total_assets": 364980, "total_liabilities": 308030, "total_equity": 56950, "cash_and_equivalents": 29943, "total_debt": 101698, "shares_outstanding": 14840 } ], "cash_flow_statements": [ { "ticker": "AAPL", "period": "FY 2025", "form_type": "10-K", "operating_cash_flow": 118254, "capital_expenditure": -12100, "free_cash_flow": 106154 } ] } }

Error responses

400 Bad Request

{ "error": "ticker parameter is required" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

report_period, sga_expense, research_and_development, and dividends_paid are currently returned as null — they are not yet extracted. cost_of_revenue and operating_expense are derived; ebit mirrors operating_income.

API reference · Filings

Filings

SEC filings for a company.

GET/api/v1/filings

Returns cached SEC filings for one ticker and calendar year. Note the form-type filter parameter is named form, not form_type.

Query parameters

Parameter	Type	Required	Description
`ticker`	string	Required	Ticker symbol. Example: AAPL.
`year`	string	Optional	Four-digit filing year. Defaults to the current year.
`form`	string	Optional	Filter by form type, e.g. 10-K, 10-Q, 8-K. Matched case-insensitively.
`limit`	integer	Optional	Maximum filings returned. Default 50, maximum 100.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/filings?ticker=AAPL&form=10-K&limit=5" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "ticker": "AAPL", "year": "2026", "total": 1, "cached_at": "2026-07-24T09:12:44.117Z", "filings": [ { "form_type": "10-K", "filing_date": "2025-10-31", "accession_number": "0000320193-25-000106", "description": "Annual report pursuant to Section 13 or 15(d)", "document_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000106/aapl-20250927.htm" } ] }

Error responses

400 Bad Request

{ "error": "ticker parameter is required" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

The document link field is document_url. Dates use filing_date, not filed_date.

API reference · Insider Transactions

Insider Transactions

Form 4 insider filings for a company.

GET/api/v1/insider/{ticker}

Returns up to 50 Form 4 filings for the ticker, taken from the cached SEC filings index. The ticker is a path segment. This endpoint returns the filing records themselves — it does not currently parse individual transactions into insider name, share count, or price fields.

Query parameters

Parameter	Type	Required	Description
`ticker`	string (path)	Required	Ticker symbol, case-insensitive. Example: AAPL.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/insider/AAPL" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "ticker": "AAPL", "count": 2, "filings": [ { "form": "4", "filing_date": "2026-05-04", "accession_number": "0000320193-26-000058", "description": "Statement of changes in beneficial ownership", "document_url": "https://www.sec.gov/Archives/edgar/data/320193/000032019326000058/xslF345X05/wf-form4.xml" } ] }

Error responses

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

A ticker with no cached filings returns 200 with count: 0 and an empty filings array rather than a 404. Parsed per-transaction fields (insider name, title, shares, price, value) are not yet exposed by this endpoint.

API reference · Investor Events

Investor Events

Corporate events and their materials.

GET/api/v1/events

Returns events for one ticker, ordered by event date. Every event currently in the platform is an earnings_call; other event types exist in the schema but are not yet populated by any automated pipeline.

Query parameters

Parameter	Type	Required	Description
`ticker`	string	Required	Ticker symbol. Example: AAPL.
`limit`	integer	Optional	Maximum events returned. Default 20, minimum 1, maximum 100.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/events?ticker=AAPL&limit=5" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "ticker": "AAPL", "count": 1, "events": [ { "ticker": "AAPL", "title": "Apple Q3 2026 Earnings Call", "event_type": "earnings_call", "event_date": "2026-07-30T21:00:00.000Z", "event_time": "17:00", "event_timezone": "America/New_York", "fiscal_period": "Q3-2026", "state": "scheduled", "press_release_url": null, "presentation_url": null, "audio_stream_url": null, "audio_download_url": null } ] }

Error responses

400 Bad Request

{ "error": "ticker parameter is required" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

Material URLs are null until the corresponding file has been captured and stored. state transitions scheduled → recording → completed (or failed).

API reference · Earnings

Earnings

Earnings materials grouped by fiscal quarter.

GET/api/v1/earnings

Returns earnings materials for one ticker, grouped by fiscal period. Each quarter exposes a materials object keyed by material type (press_release, presentation, audio); a key is present only when that material exists.

Query parameters

Parameter	Type	Required	Description
`ticker`	string	Required	Ticker symbol. Example: AAPL.
`year`	string	Optional	Filter to fiscal periods containing this year, e.g. 2026.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/earnings?ticker=AAPL&year=2026" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "ticker": "AAPL", "quarters": [ { "quarter": "Q2-2026", "materials": { "press_release": { "title": "AAPL Q2-2026 Press Release", "url": "https://…/storage/v1/object/public/earnings-materials/AAPL/Q2-2026-press-release.pdf", "date": "2026-05-01T20:30:00.000Z" }, "audio": { "title": "AAPL Q2-2026 Audio", "url": "https://…/storage/v1/object/public/earnings-audio/AAPL/Q2-2026.mp3", "date": "2026-05-01T20:30:00.000Z" } } } ] }

Error responses

400 Bad Request

{ "error": "ticker parameter is required" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

This endpoint returns a quarters array of grouped materials — it does not return flat event rows. Use /api/v1/events for event dates, times, and state.

API reference · Search

Search

Find companies by name or ticker.

GET/api/v1/companies/search

Full-text company lookup across the covered universe. A separate endpoint, GET /api/v1/search?q=, performs full-text search over the text of cached SEC documents and returns filing matches rather than company profiles.

Query parameters

Parameter	Type	Required	Description
`q`	string	Required	Search term matched against ticker and company name.
`exchange`	string	Optional	Restrict results to one exchange, e.g. NASDAQ.
`limit`	integer	Optional	Maximum results returned. Default 20.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/companies/search?q=apple" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "query": "apple", "count": 1, "companies": [ { "ticker": "AAPL", "name": "Apple Inc.", "exchange": "NASDAQ", "sector": "Technology", "country": "US" } ] }

Error responses

400 Bad Request

{ "error": "q parameter is required" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

GET /api/v1/search?q= requires a query of at least three characters and returns SEC document matches, not company records.

API reference · Metrics

Metrics

Segment financials, supplemental concepts, and LLM-extracted operational KPIs.

GET/api/v1/metrics

Returns rows from EarningsDeck's metrics registry: XBRL-derived segment revenue/operating income, supplemental income-statement concepts (R&D, SG&A, interest expense, income tax expense, D&A), and LLM-extracted qualitative KPIs (subscriber counts, same-store sales, forward guidance) that aren't tagged in XBRL at all. This is a separate endpoint from GET /api/v1/financials rather than extra fields on that response — every row here carries source_type, and llm_extracted rows always carry source_quote and confidence; financials stays a plain-numbers-only shape.

Query parameters

Parameter	Type	Required	Description
`ticker`	string	Required	Ticker symbol. Example: AAPL.
`period`	string	Optional	Exact period label, e.g. "Q2 2026". Defaults to all periods.
`metric_name`	string	Optional	Filter to one metric, e.g. "research_and_development" or a segment-derived name.
`source_type`	string	Optional	"xbrl" or "llm_extracted". Defaults to both.
`limit`	integer	Optional	Maximum rows returned. Default 100, maximum 500.

Example request

curl --request GET \ --url "https://earningsdeck.xyz/api/v1/metrics?ticker=AAPL&source_type=llm_extracted" \ --header "x-api-key: ed_live_your_api_key"

Example response

{ "ticker": "AAPL", "company": "Apple Inc.", "count": 2, "metrics": [ { "metric_name": "research_and_development", "value": 8500, "unit": "millions", "period": "Q2 2026", "filing_id": "0000320193-26-000050", "source_type": "xbrl", "source_quote": null, "confidence": null, "needs_review": false, "extracted_at": "2026-08-01T12:00:00.000Z" }, { "metric_name": "active_devices_installed_base", "value": 2200, "unit": "millions", "period": "Q2 2026", "filing_id": "0000320193-26-000050", "source_type": "llm_extracted", "source_quote": "We now have an active installed base of 2.2 billion devices.", "confidence": 0.9, "needs_review": false, "extracted_at": "2026-08-01T12:05:00.000Z" } ] }

Error responses

400 Bad Request

{ "error": "ticker parameter is required" }

401 Unauthorized

{ "error": "Invalid or missing API key" }

429 Too Many Requests

{ "error": "Rate limit exceeded", "limit": 500, "reset": "midnight UTC", "upgrade": "https://earningsdeck.xyz/pricing" }

Note

value/confidence are returned as null if the stored row has no numeric value. needs_review is set when an llm_extracted row's confidence is below the platform's review threshold — treat those as unverified until a human confirms them.