# Get financial segments Break down a company's reported revenue, operating income, assets and other financial figures by product, business or geography. ## How it works {#how-it-works} - **Choose a breakdown.** For questions about iPhone sales or revenue by region, use this tool. For company-wide amounts, use `get_financials`. Available metrics depend on the filing and can include revenue, operating income, assets, goodwill, non-current assets, property, plant and equipment, depreciation, depreciation and amortization, capital expenditure and asset additions. - **Read each group's dates and labels.** Quarterly and year-to-date flows can end on the same day. Point-in-time balances have a null start date. Reported subtotals can appear beside their components, so adding every value can double-count revenue. - **Select the report.** Use `from` and `to` for the report date, and `filing_date` or `filing_date_gte` and `filing_date_lte` for its publication date. Publication filters require a known date. Pass a `document_id` returned alongside a previous result to choose that exact report. Set `include_sources=true` to return the filing identifier and a direct link when available. - **Check coverage.** Sales channels can appear as a business breakdown. The dimension identifies the channel or geographic scope. An empty breakdown means figures are unavailable for the selected report. Pages count reports, including those with empty breakdowns. Fund share classes can return an empty report list. ## Request {#request} `GET /api/v1/financials/segments` with your API key. AI assistants call it as the `get_financial_segments` tool, with the same parameters. ``` curl "https://financialdb.ai/api/v1/financials/segments?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: annual, quarterly, interim, all | Report frequency. Interim includes quarterly and half-year reports. Default: `annual`. | | `document_id` | string | Select this exact filing regardless of period. | | `from` | date | Earliest report date, inclusive. | | `to` | date | Latest report date, inclusive. | | `known_by` | date | Only reports known to be available by this date. | | `filing_date` | date | Published on this date. | | `filing_date_gte` | date | Published on or after this date. | | `filing_date_gt` | date | Published after this date. | | `filing_date_lte` | date | Published on or before this date. | | `filing_date_lt` | date | Published before this date. | | `limit` | integer: 1–100 | Maximum number of reports. Default: `2`. | | `offset` | integer: 0–9007199254740991 | Reports to skip. Default: `0`. | ## Response {#response} JSON with these fields. A field the source doesn't report is null or left out. | Field | Description | |---|---| | `query` | Requested identifier | | `next_offset` | Offset of the next page, or null | | `reports[].document_id` | With include_sources=true, the identifier of the filing | | `reports[].filing_url` | With include_sources=true, the direct URL of the filing, or null when unavailable | | `reports[].report_date` | Date covered by the filing | | `reports[].period` | Report frequency, when known | | `reports[].currency` | Report currency, when known | | `reports[].segments[].metric` | Financial measure | | `reports[].segments[].category` | product, business or geography | | `reports[].segments[].dimension` | Reported breakdown label | | `reports[].segments[].start_date` | First day of the period, or null for a balance | | `reports[].segments[].end_date` | Last day of the period or balance date | | `reports[].segments[].currency` | Currency of the segment values | | `reports[].segments[].values[].label` | Reported segment label | | `reports[].segments[].values[].value` | Amount in currency units, or null for conflicting disclosures | | `match` | Identifier lookup outcome. A found match can still have an empty page. | ## 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).