Estimates Reference

How the estimates response is built: reported and forecast periods, GAAP and adjusted lines, omitted lines, withheld values and flags.

Estimates Reference

GET /v1/company/estimates returns a company's forward estimates, built from company guidance, a statistical model and our own AI estimate, together with the periods the company has already reported. The schema below documents every field. This page covers what the schema can't: how the periods and lines are chosen, and what the flags mean.

API Key Required
Set your API key to test the endpoints directly from the documentation.
GET/v1/company/estimates

Get model-based forward estimates for a company, with the periods it has already reported

Returns forward estimates as `data`, an array of periods in fiscal order (fiscal year ascending, then fiscal quarter, annual after that year's quarters). Each row carries the period fields the financial statements serve — `periodId` (the id the financial-periods layer mints; null when the period end cannot be established exactly or the company id is unknown, but the period is still served), `periodType`, `reportDate` (the fiscal period END date), `periodDuration`, `calendarYear`, `calendarQuarter`, `fiscalYear`, `fiscalQuarter`, and `earningsDate`/`earningsTimeOfDay` once the period is filed — with the cells under `metricsValues`, keyed by metric id. Each cell carries the estimate as `mean` (our point forecast) with its `high`/`low` range, basis (gaap/adjusted/…), confidence tier, `source` (`guidance`/`model`/`agentic_consensus`; `agentic_consensus` is our own AI estimate, not a survey of analysts), `asOf`, `actual`, flags, and guidance provenance (`provenance.guidance` is populated only for a guided cell). `data` opens with the periods the company has already reported — its last twelve reported quarters and its newest seven filed fiscal years — and then runs through the forecast horizon, ending with the last forecast fiscal year and its quarters. A forecast period whose report is overdue (about 120 days after a half-year ends, 180 after a year ends) is left out, so the forecast periods can have gaps. On a reported period each cell holds the estimate we served just before the period reported, with the company's filed number as `actual`; where we kept no pre-print estimate the estimate fields are null. Set `includeReportedPeriods=false` to get the forecast periods only. A lane meaningless for the company's sector (e.g. free cash flow for a bank) is omitted from `metricsValues` rather than served as a null cell. `primaryEpsBasis` at the top level says which EPS lane leads for the company (`gaap` or `adjusted`) — an adjusted-primary company can serve values on both lanes, so the choice cannot be read off the cells. The `eps_gaap`, `net_income`, `ebit` and `ebitda` metric ids carry the GAAP figure; `eps_adjusted`, `net_income_adjusted`, `ebit_adjusted` and `ebitda_adjusted` carry the company-adjusted one; where the company reports no adjusted figure for a line, its adjusted cells carry the GAAP figure with `basis: "gaap"`, as its filed history does. Values are served in the company's reporting currency. A key with the `estimates` feature gets every company; other keys get the free-plan companies at free-trial limits, as on the other datasets.

Parameters

companyrequired

Fiscal.ai stable company identifier (the companyFiscalIdentifier field). An alternative to ticker/micCode/exchange.

apiKeystring

API Key (alternatively send via X-Api-Key header)

includeReportedPeriodsboolean

Include the periods the company has already reported, each cell with our pre-print estimate and the filed `actual`. On unless set to `false`.

Request
https://api.fiscal.ai/v1/company/estimates
Response

Periods

  • data is in fiscal order: fiscal years ascending, each year's quarters, then its annual row.

  • It opens with the last 12 reported quarters and the newest 7 filed years. On those periods each cell keeps the estimate we served before the print, and actual holds the filed number. Pass includeReportedPeriods=false to get the forecast periods only.

  • A forecast period drops out once its report is overdue, so forecast periods can have gaps. That is 120 days after a second quarter ends, 180 days after a fourth quarter or fiscal year ends, 211 days after a first quarter and 272 days after a third quarter (a half-year filer reports those with the half).

  • periodId joins a reported period to the financials response's data[].periodId.

Lines

  • eps_gaap, net_income, ebit and ebitda carry GAAP figures. eps_adjusted, net_income_adjusted, ebit_adjusted and ebitda_adjusted carry the company's adjusted figures.

  • primaryEpsBasis says which EPS line is the company's headline; show that one first. You can't work it out from the cells, because a company whose headline is adjusted can still serve values on both lines.

  • An adjusted line is served only for a company that reports that adjusted figure itself, or in a period its own guide covers. Otherwise the cell is null with adjusted_history_insufficient. For a company that reports no adjusted figure, our AI estimate can serve on the matching GAAP line instead.

  • A line that doesn't fit the company's sector, such as free cash flow for a bank, is left out of metricsValues rather than served empty. A company's own guide on such a line is still served for the periods it covers.

  • capex is negative, the cash-flow sign. The guidance endpoint serves capex positive, as the company printed it.

  • cash_and_cash_equivalents includes short-term investments, the same figure as the financials line balance_sheet_total_cash_and_cash_equivalents.

Withheld model values

A model cell on a forecast period is null with data_unavailable in two cases besides plain gaps in the data:

  • The company has stopped reporting the line: it is missing from its last four filed quarters and its newest filed year.

  • Our latest model fit for the company failed its publish checks. Model cells stay withheld until a later fit passes; guided and AI estimate cells still serve.

Flags

Flag

Meaning

data_unavailable

Null because no value is available and no more specific flag applies.

out_year_unanchored

An out-year value was withheld as unanchored and implausible against recent results.

adjusted_history_insufficient

No adjusted value: the company doesn't report this adjusted figure, or its adjusted history is too short.

net_leverage_undefined

Net leverage isn't meaningful here (net cash, or trailing EBITDA negative or near zero).

sign_conflicts_with_recent_actuals

Withheld because its sign is opposite to a run of consistently signed reported quarters.

agentic_consensus_fy_below_booked

The AI estimate's annual figure is below what the company has already booked this year. Usually served as is, so the gap shows; on the GAAP net income and EPS lines of a company that reports no adjusted EPS, that year is withheld instead.

annual_quarter_sum_mismatch

The reported annual differs from the sum of its filed quarters by more than a small tolerance.

cyclical_trough_uncertainty

The forecast sits at a cyclical trough, where uncertainty is higher.

pre_revenue_launch_uncertainty

A pre-revenue company whose launch timing makes the forecast highly uncertain.

Provenance

provenance.guidance is filled in only on a guided cell that carries source evidence, and only for API keys with the guidance feature. Everywhere else it is null.