--- title: "Get financial statements for a company" method: GET path: "/finance/statements" tags: ["finance"] --- # Get financial statements for a company `GET /finance/statements` ## Request - Base URL: `https://www.socialcrawl.dev/v1` - URL: `https://www.socialcrawl.dev/v1/finance/statements` - Auth: API key in header `x-api-key` Returns income-statement, balance-sheet and cash-flow line items per reporting period as a unified FinancialStatementList. Line-item names match the `financials` block inside /v1/finance/quote, so both surfaces spell `net_income` the same way. Every `_delta` leaf is the period-over-period fractional change of its line item; the earliest period has nothing to compare against and reports null rather than a fabricated zero. Four leaves have no source on this surface and are always null: `currency`, `price_to_book`, `return_on_assets` and `return_on_capital` (the last two are conventionally trailing-twelve-month ratios over averaged denominators, and a single-period substitute would be a different number wearing the same name). The oldest one or two periods can arrive carrying only their identity leaves, which is what the upstream holds for them, not a fault. IMPORTANT: rows are keyed by fiscal period END, not by filing date. This surface therefore cannot support point-in-time reconstruction, and a restatement silently replaces the original figures, so a backtest built on it carries look-ahead bias. ## Query parameters - `keyword` string, required - `type` 'annual' | 'quarterly' | 'trailing' ## Headers - `Cache-Control` string - `Idempotency-Key` string ## Response `200` Successful response - object - `success` boolean, required: Whether the request succeeded - `platform` string, required: Platform name - `endpoint` string, required: API endpoint path - `data` object, required: Platform-specific response data - `items` object[]: Array of canonical financial-statement wrappers ({ financial_statement }) - `financial_statement` object: Canonical FinancialStatement object (one reporting period). Line-item names match quote.financials so both surfaces read the same - `id` string: Stable row id ("::") - `symbol` string, nullable: String at financial_statement.symbol - `statement` string, nullable: income | balance_sheet | cash_flow | combined - `period_type` string, nullable: quarterly | annual | ttm - `period_end` union: Fiscal period END, absolute UTC. NOTE: this is not a filing date. Point-in-time reconstruction and restatement detection are NOT supported on this surface - string - integer - `currency` string, nullable: Reporting currency - `revenue` integer, nullable: Numeric at financial_statement.revenue - `revenue_delta` integer, nullable: Numeric at financial_statement.revenue_delta - `operating_expense` integer, nullable: Numeric at financial_statement.operating_expense - `operating_expense_delta` integer, nullable: Numeric at financial_statement.operating_expense_delta - `net_income` integer, nullable: Numeric at financial_statement.net_income - `net_income_delta` integer, nullable: Numeric at financial_statement.net_income_delta - `net_profit_margin` integer, nullable: Numeric at financial_statement.net_profit_margin - `net_profit_margin_delta` integer, nullable: Numeric at financial_statement.net_profit_margin_delta - `earnings_per_share` integer, nullable: Numeric at financial_statement.earnings_per_share - `earnings_per_share_delta` integer, nullable: Numeric at financial_statement.earnings_per_share_delta - `ebitda` integer, nullable: Numeric at financial_statement.ebitda - `ebitda_delta` integer, nullable: Numeric at financial_statement.ebitda_delta - `effective_tax_rate` integer, nullable: Numeric at financial_statement.effective_tax_rate - `cash_and_short_term_investments` integer, nullable: Numeric at financial_statement.cash_and_short_term_investments - `cash_and_short_term_investments_delta` integer, nullable: Numeric at financial_statement.cash_and_short_term_investments_delta - `total_assets` integer, nullable: Numeric at financial_statement.total_assets - `total_assets_delta` integer, nullable: Numeric at financial_statement.total_assets_delta - `total_liabilities` integer, nullable: Numeric at financial_statement.total_liabilities - `total_liabilities_delta` integer, nullable: Numeric at financial_statement.total_liabilities_delta - `total_equity` integer, nullable: Numeric at financial_statement.total_equity - `shares_outstanding` integer, nullable: Numeric at financial_statement.shares_outstanding - `price_to_book` integer, nullable: Numeric at financial_statement.price_to_book - `return_on_assets` integer, nullable: Numeric at financial_statement.return_on_assets - `return_on_capital` integer, nullable: Numeric at financial_statement.return_on_capital - `cash_from_operations` integer, nullable: Numeric at financial_statement.cash_from_operations - `cash_from_operations_delta` integer, nullable: Numeric at financial_statement.cash_from_operations_delta - `cash_from_investing` integer, nullable: Numeric at financial_statement.cash_from_investing - `cash_from_investing_delta` integer, nullable: Numeric at financial_statement.cash_from_investing_delta - `cash_from_financing` integer, nullable: Numeric at financial_statement.cash_from_financing - `cash_from_financing_delta` integer, nullable: Numeric at financial_statement.cash_from_financing_delta - `net_change_in_cash` integer, nullable: Numeric at financial_statement.net_change_in_cash - `net_change_in_cash_delta` integer, nullable: Numeric at financial_statement.net_change_in_cash_delta - `free_cash_flow` integer, nullable: Numeric at financial_statement.free_cash_flow - `free_cash_flow_delta` integer, nullable: Numeric at financial_statement.free_cash_flow_delta - `next_cursor` string, nullable: Opaque cursor for the next page. Pass it back as a query parameter on endpoints that support pagination. Present only when the upstream reports more results. - `total` integer, nullable: Total number of matching results, when the upstream provides a count. Omitted otherwise. - `_warnings` string[]: Non-fatal notices about this response (field-map drift, clamped computed values). Advisory only: its presence never means the request failed. Omitted entirely when there is nothing to report, so treat absent as 'no warnings'. - `credits_used` integer, required: Number of credits consumed - `credits_remaining` integer, nullable, required: Current account balance, or null when this response could not establish one. Free cache hits always return null because they do not establish an authoritative post-request balance. An idempotency replay also returns null when its current-balance lookup fails. It is never a fabricated zero, so a zero here means the account really is empty. The authoritative reading is the one on a billed response, which comes straight from the deduction. - `request_id` string, required: Unique request identifier for support - `cached` boolean, required: Whether the response was served from cache - `idempotent_replay` boolean: True only when this response is an idempotency replay - `meta` object: Optional. Present only when this call completed a pattern that one other call does more cheaply or in one step, at most once per pattern per API key per day. Send the header `X-SocialCrawl-Hints: off` to never receive it. - `hint` object: One suggestion: what to call instead and why, with the price when the suggested call costs more than the calls it replaces. - `code` string: creator_card | batch_profiles | search_multi | incremental_sync | comment_labels | search_repeat - `message` string: One sentence for a person or an agent to read. - `method` string: GET or POST. - `path` string: The call the hint points to. ## Other responses - `400`: Invalid request - missing or malformed parameters - `401`: Unauthorized - missing or invalid API key - `402`: Payment required - the account balance is too low, or the calling key has spent its own per-key credit limit - `404`: Not found - the endpoint does not exist, or the requested resource was not found upstream - `405`: Method not allowed - wrong HTTP verb for this endpoint - `409`: Conflict - an idempotent request is still in flight, its completed body exceeded the replay limit, or the cohort resource is not in a state that allows this operation - `410`: Gone - the discover run's retention passed and its rows were deleted; start a new run - `413`: Payload too large: the JSON request body exceeds the 1 MB size limit and is rejected before parsing, or a single cohort result cannot fit beneath the 1 MB response-page ceiling - `422`: Idempotency payload mismatch - this Idempotency-Key was already used with a different request payload; or a discover request with async=false is over what one call can answer (NEEDS_ASYNC) - `429`: Rate or concurrency limit exceeded. `RATE_LIMITED`: more than 600 requests in a 1-minute sliding window on this API key (headers `X-RateLimit-Limit`/`Remaining`/`Reset`; `Retry-After` is seconds until the window resets). `CONCURRENCY_LIMIT`: more than 50 simultaneous in-flight requests (headers `X-Concurrency-Limit`/`Remaining`; short static `Retry-After`). Both are unbilled. Honor `Retry-After`, then back off with jitter. See /docs/rate-limits. - `500`: Internal server error - an immediate refund is attempted; credits_used reports the committed net charge and exact compensation is queued if that refund cannot commit - `502`: Upstream error - the platform returned an error; an immediate refund is attempted and credits_used reports the committed net charge - `503`: Service unavailable - the request is unbilled when rejected before deduction, otherwise an immediate refund is attempted and credits_used reports the committed net charge - `504`: Gateway timeout - the request was still running close to the platform time limit and is answered as UPSTREAM_ERROR, the same code as 502. An immediate refund is attempted and credits_used reports the committed net charge. When details.retry_with is set, retryable is false and there is no Retry-After --- [API](https://skmtc.dev/socialcrawl/apis/socialcrawl-api.md) · [All operations](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/llms.txt) · [OpenAPI document](https://skmtc.dev/socialcrawl/apis/socialcrawl-api/revisions/a0ad2511004a?raw)