--- title: "Get a financial instrument quote" method: GET path: "/finance/quote" tags: ["finance"] --- # Get a financial instrument quote `GET /finance/quote` ## Request - Base URL: `https://www.socialcrawl.dev/v1` - URL: `https://www.socialcrawl.dev/v1/finance/quote` - Auth: API key in header `x-api-key` Returns ONE rich, unified Quote for a financial instrument keyed by its `keyword` (`TICKER:EXCHANGE` for stocks/ETFs/indices, e.g. 'GOOGL:NASDAQ' / 'VOO:NYSEARCA' / '.INX:INDEXSP', or a forex/crypto pair, e.g. 'EUR-USD' / 'BTC-USD'). A single call bundles the live price + intraday graph, fundamentals (market cap, P/E, dividend yield, 52-week range, volumes), the company profile (CEO, founded, HQ, employees), quarterly + annual financials (equities), and peer instruments: all on ONE canonical shape across stocks, ETFs, indices, crypto, and forex, distinguished by `quote.type`. Forex/crypto pairs populate `quote.pair` (base/quote symbols) and have a null `ticker`. Get the exact `keyword` from /v1/finance/ticker-search. Read live from the Google Finance SERP (~5-10s). ## Query parameters - `keyword` string, required - `language` string - `location` string ## 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 - `id` string: Instrument identifier: re-feed into /v1/finance/quote ("GOOGL:NASDAQ" | ".INX:INDEXSP" | "EUR-USD") - `ticker` string, nullable: Ticker symbol (null for forex/crypto asset pairs) - `exchange` string, nullable: Primary exchange / market identifier - `name` string, nullable: Display name (e.g. 'Alphabet Inc Class A') - `type` string: Instrument class: stock | etf | index | crypto | forex | futures | fund | unknown - `url` string, nullable: String at quote.url - `currency` string, nullable: Price currency (null for asset pairs) - `pair` object, nullable: Forex/crypto base+quote symbols (null for stocks/indices) - `base_symbol` string, nullable: String at quote.pair.base_symbol - `quote_symbol` string, nullable: String at quote.pair.quote_symbol - `base_display_name` string, nullable: String at quote.pair.base_display_name - `quote_display_name` string, nullable: String at quote.pair.quote_display_name - `price` object: Price block (current, previous_close, delta, ranges, trend) - `current` integer, nullable: Numeric at quote.price.current - `previous_close` integer, nullable: Numeric at quote.price.previous_close - `delta` integer, nullable: Numeric at quote.price.delta - `percentage_delta` integer, nullable: Numeric at quote.price.percentage_delta - `trend` string, nullable: Leaf at quote.price.trend - `day_low` integer, nullable: Numeric at quote.price.day_low - `day_high` integer, nullable: Numeric at quote.price.day_high - `year_low` integer, nullable: Numeric at quote.price.year_low - `year_high` integer, nullable: Numeric at quote.price.year_high - `timestamp` string, nullable: String at quote.price.timestamp - `metrics` object, nullable: Fundamentals (market_cap, pe_ratio, dividend_yield, expense_ratio, …); null on thin rows - `market_cap` integer, nullable: Numeric at quote.metrics.market_cap - `volume` integer, nullable: Numeric at quote.metrics.volume - `avg_volume` integer, nullable: Numeric at quote.metrics.avg_volume - `pe_ratio` integer, nullable: Numeric at quote.metrics.pe_ratio - `dividend_yield` integer, nullable: Numeric at quote.metrics.dividend_yield - `ytd_return` integer, nullable: Numeric at quote.metrics.ytd_return - `expense_ratio` integer, nullable: Numeric at quote.metrics.expense_ratio - `net_assets` integer, nullable: Numeric at quote.metrics.net_assets - `yield` integer, nullable: Numeric at quote.metrics.yield - `open_interest` integer, nullable: Numeric at quote.metrics.open_interest - `category` string, nullable: String at quote.metrics.category - `metrics_currency` string, nullable: String at quote.metrics.metrics_currency - `about` object, nullable: Company profile (description, CEO, HQ, employees); equities - `description` string, nullable: String at quote.about.description - `description_source_url` string, nullable: String at quote.about.description_source_url - `ceo` string, nullable: String at quote.about.ceo - `founded` string, nullable: String at quote.about.founded - `headquarters` string, nullable: String at quote.about.headquarters - `website` string, nullable: String at quote.about.website - `employees` integer, nullable: Numeric at quote.about.employees - `graph` object[], nullable: Intraday price series ({ timestamp, value, volume }) - `timestamp` string: String at quote.graph.timestamp - `value` integer: Numeric at quote.graph.value - `volume` integer, nullable: Numeric at quote.graph.volume - `financials` object, nullable: Quarterly + annual fundamentals (equities only; null otherwise) - `quarterly` string[], nullable: Array at quote.financials.quarterly - `annual` string[], nullable: Array at quote.financials.annual - `peers` object[], nullable: Related instruments (compare_to) - `id` string: String at quote.peers.id - `ticker` string, nullable: String at quote.peers.ticker - `exchange` string, nullable: String at quote.peers.exchange - `name` string, nullable: String at quote.peers.name - `type` string: Leaf at quote.peers.type - `url` string, nullable: String at quote.peers.url - `currency` string, nullable: String at quote.peers.currency - `pair` object, nullable: Nested object: quote.peers.pair - `base_symbol` string, nullable: String at quote.peers.pair.base_symbol - `quote_symbol` string, nullable: String at quote.peers.pair.quote_symbol - `base_display_name` string, nullable: String at quote.peers.pair.base_display_name - `quote_display_name` string, nullable: String at quote.peers.pair.quote_display_name - `price` object: Nested object: quote.peers.price - `current` integer, nullable: Numeric at quote.peers.price.current - `previous_close` integer, nullable: Numeric at quote.peers.price.previous_close - `delta` integer, nullable: Numeric at quote.peers.price.delta - `percentage_delta` integer, nullable: Numeric at quote.peers.price.percentage_delta - `trend` string, nullable: Leaf at quote.peers.price.trend - `day_low` integer, nullable: Numeric at quote.peers.price.day_low - `day_high` integer, nullable: Numeric at quote.peers.price.day_high - `year_low` integer, nullable: Numeric at quote.peers.price.year_low - `year_high` integer, nullable: Numeric at quote.peers.price.year_high - `timestamp` string, nullable: String at quote.peers.price.timestamp - `metrics` object, nullable: Nested object: quote.peers.metrics - `market_cap` integer, nullable: Numeric at quote.peers.metrics.market_cap - `volume` integer, nullable: Numeric at quote.peers.metrics.volume - `avg_volume` integer, nullable: Numeric at quote.peers.metrics.avg_volume - `pe_ratio` integer, nullable: Numeric at quote.peers.metrics.pe_ratio - `dividend_yield` integer, nullable: Numeric at quote.peers.metrics.dividend_yield - `ytd_return` integer, nullable: Numeric at quote.peers.metrics.ytd_return - `expense_ratio` integer, nullable: Numeric at quote.peers.metrics.expense_ratio - `net_assets` integer, nullable: Numeric at quote.peers.metrics.net_assets - `yield` integer, nullable: Numeric at quote.peers.metrics.yield - `open_interest` integer, nullable: Numeric at quote.peers.metrics.open_interest - `category` string, nullable: String at quote.peers.metrics.category - `metrics_currency` string, nullable: String at quote.peers.metrics.metrics_currency - `ext` string, nullable: Leaf at quote.ext - `_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)