# Get reported earnings Summarize a company’s earnings in one row per period, with revenue, profit, EPS, cash flow and headline margins and growth. ## How it works {#how-it-works} - **Choose the right tool.** For a line item such as operating expenses, use `get_financials`. For a ratio trend such as return on equity, use `get_financial_metrics`. - **Choose the period type.** `quarterly` (the default), `half_year`, `annual`, `ttm` for trailing twelve months, or `reported` for exactly what was filed. Five years of annual results is `period=annual&limit=5`. - **If you don't choose, you get what the company actually reports.** US companies report quarters. Most UK and European companies don't, so you get half-years, or years if there are no half-years either. Tesco (`TSCO:LN`) comes back annual. - **Some periods are arithmetic, and we show the arithmetic.** Companies rarely file a standalone fourth quarter; they file the full year. So Q4 is the full year minus the first nine months, and `include_sources=true` shows the calculation with both filings. - **Converted figures keep their originals.** `currency=USD` converts amounts and EPS at each period's average rate. Amounts without a usable rate are null. The figures as filed, in the currency they were filed in, are available in `provenance` when you request sources. - **`known_by` gives you what was known at the time.** `known_by=2024-01-01` uses only evidence available by that date. Later restatements stay out, which matters in a backtest: the market in 2023 didn't know about the 2024 restatement either. - **An empty answer tells you what does exist, and costs nothing.** Ask for quarters from a company that reports only years and you get an empty list, a `message` saying so, and `available_periods` listing what it does report. ## Request {#request} `GET /api/v1/earnings` with your API key. AI assistants call it as the `get_earnings` tool, with the same parameters. ``` curl "https://financialdb.ai/api/v1/earnings?q=AAPL:US" \ -H "Authorization: Bearer $FDB_API_KEY" ``` ## Parameters {#parameters} | Parameter | Type | Description | |---|---|---| | `include_sources` | boolean | Include available source documents and supporting evidence. Omit for data only. Default: `false`. | | `q` (required) | string | Ticker with its exchange code or MIC (AAPL:US, AAPL:XNAS, TSCO:XLON), ISIN, CUSIP, SEDOL, WKN, FIGI, LEI, CIK or company registration number. Any ticker and mic a listing returns work as ticker:mic. | | `period` | string: quarterly, half_year, annual, ttm, reported | Period type. Default: quarterly, or what the company reports. | | `currency` | string | Currency to convert amounts and EPS to, such as USD. Default: as reported. | | `from` | date | Only periods ending on or after this date. | | `to` | date | Only periods ending on or before this date. | | `known_by` | date | Use evidence available on or before this date. | | `available_on` | date | Evidence available on this date. | | `available_on_gte` | date | Evidence available on or after this date. | | `available_on_gt` | date | Evidence available after this date. | | `available_on_lte` | date | Evidence available on or before this date. | | `available_on_lt` | date | Evidence available before this date. | | `limit` | integer: 1–100 | Periods to return. Default: `20`. | | `offset` | integer: 0–9007199254740991 | Periods to skip. Use next_offset from the previous page. Default: `0`. | ## Response {#response} JSON with these fields. A field the source doesn't report is null or left out. When nothing matches, `message` says why and what to ask instead, and `available_periods` lists what the company has. Empty answers are free. | Field | Description | |---|---| | `query` | The identifier asked for | | `earnings[].start_date` | First day of the period | | `earnings[].end_date` | Last day of the period | | `earnings[].period` | annual, quarterly, half_year, ttm or interim | | `earnings[].fiscal_year` | Fiscal year of the period, when established | | `earnings[].fiscal_period` | Fiscal period label, such as FY, Q1–Q4 or H1–H2 | | `earnings[].reporting_currency` | Currency the company reported in | | `earnings[].currency` | Currency of the amounts and EPS in this response | | `earnings[].currency_conversion.from` | Currency converted from | | `earnings[].currency_conversion.rate` | Rate applied | | `earnings[].currency_conversion.method` | How the rate was derived | | `earnings[].currency_conversion.rate_start_date` | First day the rate covers | | `earnings[].currency_conversion.rate_end_date` | Last day the rate covers | | `earnings[].revenue` | Revenue | | `earnings[].net_income` | Profit or loss attributable to shareholders of the parent: the figure EPS is based on | | `earnings[].net_income_including_non_controlling_interests` | Consolidated profit or loss, including the share of non-controlling interests | | `earnings[].net_income_available_to_common_shareholders` | Profit available to common shareholders | | `earnings[].earnings_per_share` | Basic EPS | | `earnings[].earnings_per_share_diluted` | Diluted EPS | | `earnings[].weighted_average_shares` | Weighted average shares, basic | | `earnings[].weighted_average_shares_diluted` | Weighted average shares, diluted | | `earnings[].cost_of_revenue` | Cost of revenue | | `earnings[].gross_profit` | Gross profit | | `earnings[].operating_income` | Operating profit or loss | | `earnings[].pretax_income` | Profit or loss before tax | | `earnings[].income_tax_expense` | Income tax expense | | `earnings[].ebit` | Pretax income plus compatible interest expense; null when unavailable | | `earnings[].net_cash_flow_from_operations` | Net cash from operating activities for this exact period | | `earnings[].net_cash_flow_from_investing` | Net cash from investing activities for this exact period | | `earnings[].net_cash_flow_from_financing` | Net cash from financing activities for this exact period | | `earnings[].capital_expenditure` | Cash spent on property, plant and equipment, negative for an outflow | | `earnings[].free_cash_flow` | Operating cash flow plus signed capital expenditure; missing inputs are not zero | | `earnings[].gross_margin` | Gross profit / revenue, as a decimal ratio; null for non-positive revenue | | `earnings[].operating_margin` | Operating income / revenue, as a decimal ratio; null for non-positive revenue | | `earnings[].net_margin` | Net income (attributable to the parent) / revenue, as a decimal ratio; null for non-positive revenue | | `earnings[].net_margin_including_non_controlling_interests` | Consolidated net income, including non-controlling interests, / revenue, as a decimal ratio; null for non-positive revenue | | `earnings[].free_cash_flow_margin` | Free cash flow / revenue, as a decimal ratio; null for non-positive revenue | | `earnings[].revenue_growth` | Year-over-year revenue growth as a decimal ratio in reporting currency; null for missing or non-positive base | | `earnings[].earnings_growth` | Year-over-year parent-profit growth as a decimal ratio in reporting currency; null for missing or non-positive base | | `earnings[].operating_income_growth` | Year-over-year operating-income growth as a decimal ratio in reporting currency; null for missing or non-positive base | | `earnings[].earnings_per_share_growth` | Year-over-year basic EPS growth as a decimal ratio; null for an incompatible share basis or missing/non-positive base | | `earnings[].free_cash_flow_growth` | Year-over-year free-cash-flow growth as a decimal ratio in reporting currency; null for missing or non-positive base | | `earnings[].available_on` | Latest known availability date of evidence contributing to these figures, including comparisons | | `earnings[].income_statement_available_on` | Availability date of the underlying income statement | | `earnings[].provenance[].field` | Response field explained by this evidence | | `earnings[].provenance[].value` | Value in this response, after any currency conversion | | `earnings[].provenance[].derivation` | Reported, or the method used to derive the figure; null when unknown | | `earnings[].provenance[].inputs[].field` | Input metric for a ratio or growth calculation; numerator/current first, denominator/prior second | | `earnings[].provenance[].inputs[].value` | Input value in reporting currency | | `earnings[].provenance[].inputs[].start_date` | Input period start | | `earnings[].provenance[].inputs[].end_date` | Input period end | | `earnings[].provenance[].inputs[].currency` | Input reporting currency | | `earnings[].provenance[].sources[].document_id` | Filing directory key when available | | `earnings[].provenance[].sources[].source_document_id` | Original source identifier, such as an SEC accession | | `earnings[].provenance[].sources[].form` | Filing form or document type | | `earnings[].provenance[].sources[].filing_date` | Date this source filing was published | | `earnings[].provenance[].sources[].url` | Direct source filing URL; null when no document URL is available | | `earnings[].provenance[].sources[].concept` | Reported concept or source line label used to locate the figure | | `earnings[].provenance[].sources[].value` | Original reported value as a string, before output currency conversion | | `earnings[].provenance[].sources[].unit` | Original unit, including currency or currency per share | | `earnings[].provenance[].sources[].start_date` | Original reported period start | | `earnings[].provenance[].sources[].end_date` | Original reported period end | | `next_offset` | offset of the next page, null on the last | | `match` | Identifier lookup outcome. A found match can still have an empty page. | | `message` | Only when no periods match: why, and what to ask instead | | `available_periods[].period` | Only when no periods match: a period type the company has (quarterly, half_year, annual, ttm) | | `available_periods[].count` | Periods of that type | | `available_periods[].earliest_end_date` | End of the earliest | | `available_periods[].latest_end_date` | End of the latest | ## Errors {#errors} | Status | Meaning | |---|---| | 400 | Missing, unknown or invalid parameter, or an identifier that can't be looked up | | 401 | Missing, unknown or revoked API key | | 402 | No active plan or trial, or the included request allowance is used | | 403 | API access of the account is suspended | | 404 | The identifier matches nothing or is ambiguous. The match field identifies the outcome | | 429 | Over the plan's rate limit; Retry-After says when to retry | | 500 | Internal error; the same request is unlikely to succeed on retry | | 503 | The data couldn't be loaded right now; Retry-After says when to retry, when known | Errors are JSON with an `error` message saying what to fix. Errors are free. See [Errors and limits](https://financialdb.ai/documentation/api/errors-and-limits.md).