{"openapi":"3.1.0","info":{"title":"gfin API Reference","version":"0.1.0","description":"Google Finance source API contract for bluedoor Financial Data.\n\nSource-native Google Finance-backed routes for symbol search, quotes, market summaries, news, and research.\n\nHosted, cached, AI-friendly market data API backed by Google Finance.","x-bluedoor-source":{"source_id":"gfin","adapter_slug":"google-finance","upstream":"google.com/finance","docs_url":"https://bluedoor.sh/apis/financial-data/sources/gfin"}},"servers":[{"url":"https://api.gfin.dev","description":"Current source API host"},{"url":"https://api.bluedoor.sh/adapters/google-finance","description":"bluedoor adapter namespace"}],"tags":[{"name":"System","description":"Health, OpenAPI, and public route catalog."},{"name":"Search","description":"Symbol, company, and finance-entity discovery."},{"name":"Research","description":"Natural-language finance research workflows."},{"name":"Markets","description":"Market summaries, notable stocks, events, and highlights."},{"name":"News","description":"Finance news feeds and story collections."},{"name":"Quotes","description":"Quote summaries, details, history, financials, earnings, related entities, and sentiment."},{"name":"Realtime","description":"Realtime price snapshots and trend lines."},{"name":"User Context","description":"User-context routes that may return empty data for anonymous requests."}],"components":{"schemas":{"GenericSuccessResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/FinanceData"}},"required":["meta","data"],"additionalProperties":true},"HealthResponse":{"type":"object","properties":{"ok":{"type":"boolean","const":true},"name":{"type":"string","description":"Service name."},"version":{"type":"string","description":"API version."},"data_source":{"type":"string","const":"google_finance","description":"Source used by gfin for this route family."},"route_count":{"type":"integer","description":"Number of currently available public routes."},"cache":{"type":"object","properties":{"cached_reads":{"type":"boolean"},"stale_if_error":{"type":"boolean"},"request_coalescing":{"type":"boolean"}}},"identity":{"type":"object","description":"Public identity and rate-limit policy.","additionalProperties":true}},"required":["ok","name","version","data_source","route_count","cache","identity"]},"RouteCatalogResponse":{"type":"object","properties":{"route_count":{"type":"integer"},"data_source":{"type":"string","const":"google_finance"},"identity_policy":{"type":"object","description":"Public identity and rate-limit policy.","additionalProperties":true},"routes":{"type":"object","description":"Map of public route names to public paths.","additionalProperties":{"$ref":"#/components/schemas/RouteCatalogRoute"}}},"required":["route_count","data_source","identity_policy","routes"]},"RouteCatalogRoute":{"type":"object","properties":{"path":{"type":"string","description":"Public gfin path."},"summary":{"type":"string","description":"Short route label."},"description":{"type":"string","description":"Finance-domain route description."}},"required":["path","summary","description"]},"AuthOtpRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"}},"required":["email"],"additionalProperties":false},"AuthVerifyRequest":{"type":"object","properties":{"email":{"type":"string","format":"email"},"code":{"type":"string","pattern":"^\\d{6}$"},"create_key":{"type":"boolean","default":true},"label":{"type":"string"},"expires_in_days":{"type":"integer","minimum":1,"maximum":365}},"required":["email","code"],"additionalProperties":false},"AuthLimitRequest":{"type":"object","properties":{"requested_rps":{"type":"number","minimum":0},"requested_origin_rps":{"type":"number","minimum":0},"use_case":{"type":"string"},"message":{"type":"string"}},"additionalProperties":false},"ResponseMeta":{"type":"object","properties":{"provider":{"type":"string","const":"google_finance"},"route":{"type":"string","description":"Public gfin route name."},"cache":{"type":"string","description":"Cache state for this response."},"ttl_seconds":{"type":"integer","minimum":0},"stale_seconds":{"type":"integer","minimum":0},"generated_at":{"type":"string","format":"date-time"},"request_id":{"type":"string"},"identity_tier":{"type":"string","description":"Rate-limit identity tier used for this request."}},"required":["provider","route","cache","ttl_seconds","stale_seconds","generated_at","request_id","identity_tier"],"additionalProperties":true},"FinanceData":{"description":"Route-specific finance data. Common quote, news, search, earnings, and price-series routes are projected into named fields; less structured route families return finance records without backend transport identifiers.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"ErrorDetail":{"type":"object","properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string","description":"Human-readable error message."},"next_action":{"type":"string","description":"Recommended client action."},"request_id":{"type":"string","description":"Request ID for logs and support."}},"required":["code","message","next_action","request_id"],"additionalProperties":true},"ErrorResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"},"meta":{"type":"object","description":"Response metadata when available.","additionalProperties":true},"rate_limit":{"type":"object","description":"Rate-limit detail when available.","additionalProperties":true}},"required":["error"],"additionalProperties":true},"RateLimitResponse":{"type":"object","properties":{"error":{"$ref":"#/components/schemas/ErrorDetail"},"rate_limit":{"type":"object","properties":{"scope":{"type":"string","enum":["request","source_fetch","origin","research","auth","limit_request"]},"tier":{"type":"string","enum":["anonymous","contact","key","auth"]},"reason":{"type":"string"},"retry_after_seconds":{"type":"integer","minimum":1},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}]},"remaining":{"type":"integer","minimum":0},"reset_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"upgrade":{"type":"string"}},"required":["scope","tier","reason","retry_after_seconds","limit","remaining","reset_at","upgrade"],"additionalProperties":true}},"required":["error","rate_limit"],"additionalProperties":false},"SymbolsSearchData":{"description":"Search results with symbol, exchange, name, quote snapshot, and instrument identifiers when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"SymbolsSearchResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SymbolsSearchData"}},"required":["meta","data"],"additionalProperties":true},"ResearchData":{"description":"Research result for the requested natural-language finance query, including answer text and citations when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"ResearchResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/ResearchData"}},"required":["meta","data"],"additionalProperties":true},"MarketSummaryData":{"description":"Market themes, summaries, related stories, and current market context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketSummaryResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketSummaryData"}},"required":["meta","data"],"additionalProperties":true},"MarketMoversData":{"description":"Notable instruments, quote snapshots, and supporting discovery context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketMoversResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketMoversData"}},"required":["meta","data"],"additionalProperties":true},"MarketEventsData":{"description":"Finance events, dates, event categories, and related symbols when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketEventsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketEventsData"}},"required":["meta","data"],"additionalProperties":true},"NewsData":{"description":"Finance news stories with URLs, titles, publishers, timestamps, related instruments, and snippets when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"NewsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/NewsData"}},"required":["meta","data"],"additionalProperties":true},"NewsCollectionsData":{"description":"Finance story collections with story groups and related metadata when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"NewsCollectionsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/NewsCollectionsData"}},"required":["meta","data"],"additionalProperties":true},"MarketHighlightsData":{"description":"Featured market highlights and supporting finance context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"MarketHighlightsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/MarketHighlightsData"}},"required":["meta","data"],"additionalProperties":true},"QuoteData":{"description":"Compact quote snapshot for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"QuoteResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/QuoteData"}},"required":["meta","data"],"additionalProperties":true},"QuoteDetailsData":{"description":"Expanded quote details for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"QuoteDetailsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/QuoteDetailsData"}},"required":["meta","data"],"additionalProperties":true},"QuoteProfileData":{"description":"Company or instrument profile data for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"QuoteProfileResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/QuoteProfileData"}},"required":["meta","data"],"additionalProperties":true},"PricesHistoryData":{"description":"Historical price observations for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"PricesHistoryResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/PricesHistoryData"}},"required":["meta","data"],"additionalProperties":true},"FinancialsData":{"description":"Financial statement and metric data for the requested symbol when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"FinancialsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/FinancialsData"}},"required":["meta","data"],"additionalProperties":true},"EarningsData":{"description":"Earnings history and expectations for the requested symbol when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"EarningsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/EarningsData"}},"required":["meta","data"],"additionalProperties":true},"RelatedAssetsData":{"description":"Related instruments, peers, and comparable entities for the requested symbol.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"RelatedAssetsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/RelatedAssetsData"}},"required":["meta","data"],"additionalProperties":true},"SentimentData":{"description":"Sentiment-oriented data for the requested symbol when available.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"SentimentResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/SentimentData"}},"required":["meta","data"],"additionalProperties":true},"RealtimeQuotesData":{"description":"Realtime quote snapshots for the requested finance entities.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"RealtimeQuotesResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/RealtimeQuotesData"}},"required":["meta","data"],"additionalProperties":true},"RealtimeTrendsData":{"description":"Realtime trend-line observations for the requested finance entities.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"RealtimeTrendsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/RealtimeTrendsData"}},"required":["meta","data"],"additionalProperties":true},"WatchlistsData":{"description":"Watchlist data available to the request context.","anyOf":[{"type":"object","additionalProperties":true},{"type":"array","items":{}},{"type":"string"},{"type":"number"},{"type":"integer"},{"type":"boolean"},{"type":"null"}]},"WatchlistsResponse":{"type":"object","properties":{"meta":{"$ref":"#/components/schemas/ResponseMeta"},"data":{"$ref":"#/components/schemas/WatchlistsData"}},"required":["meta","data"],"additionalProperties":true}}},"paths":{"/v1/health":{"get":{"tags":["System"],"operationId":"getHealth","summary":"Service health.","description":"Returns basic gfin service status, cache policy, identity policy, and the number of currently shipped public routes.","responses":{"200":{"description":"Health response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"name":"gfin","version":"0.1.0","data_source":"google_finance","route_count":19,"cache":{"cached_reads":true,"stale_if_error":true,"request_coalescing":true},"identity":{"anonymous":"Works without setup with IP-based request limits.","contact":"Send X-Gfin-Contact for higher no-key limits and support metadata.","auth":"Create API keys by requesting an email code at /v1/auth/otp and verifying it at /v1/auth/verify.","key":"Send Authorization: Bearer <api_key> or X-Gfin-Key for higher free limits.","limits":"When key-tier limits are too low, email sam@gfin.dev or POST /v1/auth/limits/requests. Programmatic requests are limited to 1 per minute per API key.","research":"Natural-language research is constrained separately; default public research budget is 1 request per minute per identity."}}}}}}}}}},"/v1/endpoints":{"get":{"tags":["System"],"operationId":"listRoutesLegacy","summary":"Route Catalog","description":"Returns the machine-readable catalog of supported public gfin routes. This legacy path is kept as an alias for /v1/routes.","parameters":[],"responses":{"200":{"description":"Route catalog.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteCatalogResponse"},"examples":{"success":{"summary":"Success","value":{"route_count":19,"data_source":"google_finance","identity_policy":{"anonymous":"Works without setup with IP-based request limits.","contact":"Send X-Gfin-Contact for higher no-key limits and support metadata.","auth":"Create API keys by requesting an email code at /v1/auth/otp and verifying it at /v1/auth/verify.","key":"Send Authorization: Bearer <api_key> or X-Gfin-Key for higher free limits.","limits":"When key-tier limits are too low, email sam@gfin.dev or POST /v1/auth/limits/requests. Programmatic requests are limited to 1 per minute per API key.","research":"Natural-language research is constrained separately; default public research budget is 1 request per minute per identity."},"routes":{"symbols_search":{"path":"/v1/symbols/search","summary":"Symbol Search","description":"Returns symbol and instrument search results for text input."},"quote":{"path":"/v1/quotes/{symbol}","summary":"Quote","description":"Returns a compact quote snapshot for one symbol."},"research":{"path":"/v1/research","summary":"Research","description":"Runs a natural-language finance research query and returns an answer-oriented finance research result."}}}}}}}}}}},"/v1/routes":{"get":{"tags":["System"],"operationId":"listRoutes","summary":"Route Catalog","description":"Returns the machine-readable catalog of supported public gfin routes. Use this for tool discovery, code generation, and agents that need to inspect available finance data routes programmatically.","parameters":[],"responses":{"200":{"description":"Route catalog.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RouteCatalogResponse"},"examples":{"success":{"summary":"Success","value":{"route_count":19,"data_source":"google_finance","identity_policy":{"anonymous":"Works without setup with IP-based request limits.","contact":"Send X-Gfin-Contact for higher no-key limits and support metadata.","auth":"Create API keys by requesting an email code at /v1/auth/otp and verifying it at /v1/auth/verify.","key":"Send Authorization: Bearer <api_key> or X-Gfin-Key for higher free limits.","limits":"When key-tier limits are too low, email sam@gfin.dev or POST /v1/auth/limits/requests. Programmatic requests are limited to 1 per minute per API key.","research":"Natural-language research is constrained separately; default public research budget is 1 request per minute per identity."},"routes":{"symbols_search":{"path":"/v1/symbols/search","summary":"Symbol Search","description":"Returns symbol and instrument search results for text input."},"quote":{"path":"/v1/quotes/{symbol}","summary":"Quote","description":"Returns a compact quote snapshot for one symbol."},"research":{"path":"/v1/research","summary":"Research","description":"Runs a natural-language finance research query and returns an answer-oriented finance research result."}}}}}}}}}}},"/v1/auth/otp":{"post":{"tags":["System"],"operationId":"requestAuthOtp","summary":"Request email verification code.","description":"Sends a short-lived email verification code used to create or manage gfin API keys.","requestBody":{"required":true,"description":"Email verification request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthOtpRequest"},"examples":{"request":{"summary":"Request","value":{"email":"you@example.com"}}}}}},"responses":{"202":{"description":"Verification code accepted for delivery.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"email":"you@example.com","expires_in_seconds":600,"delivery":"email"}}}}}}},"400":{"description":"Invalid email or JSON body.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Bad Request","value":{"error":{"code":"bad_request","message":"A valid email is required.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"503":{"description":"Auth storage or email delivery is unavailable.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"auth_not_configured":{"summary":"Auth Not Configured","value":{"error":{"code":"auth_not_configured","message":"API key authentication is not configured.","next_action":"fix_auth","request_id":"req_example"}}}}}}}}}},"/v1/auth/verify":{"post":{"tags":["System"],"operationId":"verifyAuthOtp","summary":"Verify email code.","description":"Verifies an email code, returns a short-lived management token, and creates an API key by default.","requestBody":{"required":true,"description":"Email code verification request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthVerifyRequest"},"examples":{"request":{"summary":"Request","value":{"email":"you@example.com","code":"123456"}}}}}},"responses":{"200":{"description":"Email verified.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"email":"you@example.com","management_token":"gfin_mgmt_...","token_type":"Bearer","management_expires_in_seconds":900,"api_key":"gfin_live_...","key":{"id":"0123456789abcdef01234567","email":"you@example.com","label":"default","requests_per_minute":30000,"origin_per_minute":3000}}}}}}}},"400":{"description":"Invalid or expired code.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_code":{"summary":"Invalid Code","value":{"error":{"code":"invalid_code","message":"Verification code is invalid or expired.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"503":{"description":"Auth storage is unavailable.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"auth_not_configured":{"summary":"Auth Not Configured","value":{"error":{"code":"auth_not_configured","message":"API key authentication is not configured.","next_action":"fix_auth","request_id":"req_example"}}}}}}}}}},"/v1/auth/limits/requests":{"post":{"tags":["System"],"operationId":"requestLimitIncrease","summary":"Request custom rate limits.","description":"Submits a custom rate-limit request for the authenticated API key. This route is limited to 1 request per minute per API key.","parameters":[{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"requestBody":{"required":true,"description":"Requested custom rate limits and use case.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuthLimitRequest"},"examples":{"request":{"summary":"Request","value":{"requested_rps":100,"use_case":"production agent workload"}}}}}},"responses":{"202":{"description":"Custom rate-limit request received.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenericSuccessResponse"},"examples":{"success":{"summary":"Success","value":{"ok":true,"data":{"id":"req_example","email":"you@example.com","status":"received","notification":{"mode":"email"},"message":"Custom rate-limit request received. You can also email sam@gfin.dev."}}}}}}},"401":{"description":"API key is required.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"api_key_required":{"summary":"Api Key Required","value":{"error":{"code":"api_key_required","message":"API key is required to request custom rate limits.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}}}}},"/v1/symbols/search":{"get":{"tags":["Search"],"operationId":"getSymbolsSearch","summary":"Symbol Search","description":"Returns symbol and instrument search results for text input.\n\nUse this for search boxes, ticker resolution, company lookup, and agents that need to turn user text into finance entities.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Search text such as a company name, fund name, index name, or partial ticker. Aliases: query, term."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Symbol Search response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SymbolsSearchResponse"},"examples":{"success":{"summary":"Symbols Search success","value":{"meta":{"provider":"google_finance","route":"symbols_search","cache":"miss","ttl_seconds":3600,"stale_seconds":43200,"generated_at":"2026-05-28T21:59:26.653Z","request_id":"884f265d-8e51-4f62-afff-eb0c1c881d06","identity_tier":"anonymous"},"data":{"resource":"search_results","query":"apple","results":[]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Search requires q= with a company name, instrument name, or ticker.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"symbols_search","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/research":{"get":{"tags":["Research"],"operationId":"getResearch","summary":"Research","description":"Runs a natural-language finance research query and returns an answer-oriented result.\n\nThis route is intentionally more constrained than ordinary market-data routes because it can invoke a scarce upstream inference resource.","parameters":[{"name":"q","in":"query","required":true,"schema":{"type":"string"},"description":"Natural-language finance research query. Aliases: query, term."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Research response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ResearchResponse"},"examples":{"success":{"summary":"Research success","value":{"meta":{"provider":"google_finance","route":"research","cache":"miss","ttl_seconds":3600,"stale_seconds":43200,"generated_at":"2026-05-28T21:59:31.260Z","request_id":"6e573204-0e3f-4cf5-b7e4-1179be5a3379","identity_tier":"anonymous"},"data":{"resource":"research_answer","query":"Why is AAPL moving today?","answer":null,"citations":[],"status":"not_available"}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Research requires q= with a natural-language finance question.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"research","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/summary":{"get":{"tags":["Markets"],"operationId":"getMarketSummary","summary":"Market Summary","description":"Returns broad market summary data and narrative market context.\n\nUse this for market overview pages, opening dashboards, daily summaries, and agents that need current market context before drilling into individual symbols.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Summary response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketSummaryResponse"},"examples":{"success":{"summary":"Market Summary success","value":{"meta":{"provider":"google_finance","route":"market_summary","cache":"miss","ttl_seconds":60,"stale_seconds":720,"generated_at":"2026-05-28T21:59:31.928Z","request_id":"041592f5-d641-42f5-8c8f-5969e9145c32","identity_tier":"anonymous"},"data":{"resource":"market_summary","themes":[{"title":"Major indexes reach historic highs as tech leads gains","summary":"On May 28, 2026, the S&P 500 and Nasdaq Composite closed at record levels, rising 0.58% and 0.91% respectively. The gains were primarily driven by a surge in technology stocks and positive corporate earnings that helped the market reverse early losses.","stories":[{"url":"https://www.fool.com/coverage/stock-market-today/2026/05/28/stock-market-today-may-28-inflation-isn-t-stopping-this-stock-market-rally/","title":"Stock Market Today, May 28: Inflation Isn't Stopping This Stock Market Rally","publisher":"www.fool.com","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn2.gstatic.com/faviconV2?url=https://www.fool.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"Today, May 28, 2026, Snowflake's surge on robust earnings and a multibillion‑dollar Amazon pact helped tech lead U.S. stocks to fresh gains. By Emma Newbery – May 28, 2026 at 5:30PM EST. Summarize with AI. The S&P 500 (^GSPC +0.58%) rose 0.58% to 7,563.63, the Nasdaq Composite (^IXIC +0.91%) gained 0.91% to 26,917.47 as stocks reversed early losses to close near record highs despite hotter PCE inflation. The Dow Jones Industrial Average (^DJI +0.05%) inched up 0.05% to 50,668.97. Market movers. Snowflake jumped 36% after strong Q1 results and a $6 billion Amazon deal, while Microsoft climbed on analyst optimism and plans to build in‑house AI models. In contrast, Salesforce dipped despite yes..."},{"url":"https://www.cnbc.com/2026/05/27/stock-market-today-live-updates.html","title":"S&P 500 and Nasdaq close at new records, lifted by tech rally: Live updates","publisher":"CNBC","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn0.gstatic.com/faviconV2?url=https://www.cnbc.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"Sarah Min. Lisa Kailai Han. Traders work at the New York Stock Exchange on May 28, 2026. NYSE. The S&P 500 and Nasdaq Composite closed at records on Thursday as tech resumed its leadership, and traders weighed a reported agreement between U.S. and Iranian negotiators to extend the ceasefire. The broader index gained 0.58% to 7,563.63, while the Nasdaq Composite rose 0.91% to 26,917.47. Both indexes also hit intraday all-time highs. The Dow Jones Industrial Average was higher by 0.05% at 50,668.97."},{"url":"https://www.investopedia.com/stock-market-today-dow-jones-s-and-p-500-05282026-11985218","title":"Markets News, May 28, 2026: Indexes Close at Fresh Records as Inflation Data Softer Than Expected; Oil Pulls Back","publisher":"Investopedia","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn1.gstatic.com/faviconV2?url=https://www.investopedia.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"By. Aaron Rennie. A former Senior Publishing Editor on the Dow Jones Newswires team at The Wall Street Journal, Aaron earned a Bachelor's degree in Economics from the University of Michigan and a Master's in Journalism from Columbia University. Learn about our editorial policies. Updated May 28, 2026. 04:11 PM EDT. Snowflake shares soared Thursday after stronger-than-expected results and a $6 billion Amazon Web Services contract. ANGELA WEISS / AFP via Getty Images. All three major U.S. stock indexes closed at records for a second straight day as monthly inflation data rose less than expected and oil prices headed lower. The tech-heavy Nasdaq Composite, benchmark S&P 500, and blue-chip Dow J..."}]},{"title":"Snowflake shares soar following Amazon partnership and earnings beat","summary":"Snowflake shares surged approximately 36% after the company reported strong first-quarter financial results and announced a $6 billion deal with Amazon Web Services over the next five years. This performance revitalized investor enthusiasm for the broader artificial intelligence and cloud software sectors.","stories":[{"url":"https://www.fool.com/coverage/stock-market-today/2026/05/28/stock-market-today-may-28-inflation-isn-t-stopping-this-stock-market-rally/","title":"Stock Market Today, May 28: Inflation Isn't Stopping This Stock Market Rally","publisher":"www.fool.com","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn2.gstatic.com/faviconV2?url=https://www.fool.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"Today, May 28, 2026, Snowflake's surge on robust earnings and a multibillion‑dollar Amazon pact helped tech lead U.S. stocks to fresh gains. By Emma Newbery – May 28, 2026 at 5:30PM EST. Summarize with AI. The S&P 500 (^GSPC +0.58%) rose 0.58% to 7,563.63, the Nasdaq Composite (^IXIC +0.91%) gained 0.91% to 26,917.47 as stocks reversed early losses to close near record highs despite hotter PCE inflation. The Dow Jones Industrial Average (^DJI +0.05%) inched up 0.05% to 50,668.97. Market movers. Snowflake jumped 36% after strong Q1 results and a $6 billion Amazon deal, while Microsoft climbed on analyst optimism and plans to build in‑house AI models. In contrast, Salesforce dipped despite yes..."},{"url":"https://www.cnbc.com/2026/05/27/stock-market-today-live-updates.html","title":"S&P 500 and Nasdaq close at new records, lifted by tech rally - CNBC","publisher":"www.cnbc.com","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn0.gstatic.com/faviconV2?url=https://www.cnbc.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"S&P 500 and Nasdaq close at new records, lifted by tech rally: Live updates. Sarah Min. Lisa Kailai Han. Traders work at the New York Stock Exchange on May 28, 2026. NYSE. The S&P 500 and Nasdaq Composite closed at records on Thursday as tech resumed its leadership, and traders weighed a reported agreement between U.S. and Iranian negotiators to extend the ceasefire. The broader index gained 0.58% to 7,563.63, while the Nasdaq Composite rose 0.91% to 26,917.47. Both indexes also hit intraday all-time highs. The Dow Jones Industrial Average was higher by 0.05% at 50,668.97. Tech stocks rallied Thursday, after a strong earnings outlook from Snowflake revived enthusiasm around the AI trade. Sha..."},{"url":"https://www.fool.com/coverage/stock-market-today/2026/05/28/stock-market-today-may-28-tech-stocks-rise-as-snowflake-surges-after-usd6-billion-amazon-deal-and-strong-earnings/","title":"Stock Market Today, May 28: Tech Stocks Rise as Snowflake Surges ...","publisher":"www.fool.com","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn2.gstatic.com/faviconV2?url=https://www.fool.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"What this means for investors. Snowflake is today's headlining stock, rising 38% after reporting Q1 earnings after earnings yesterday. The cloud-based data platform provider grew sales by 33%, agreed to a $6 billion deal with Amazon, and now counts 813 of the Forbes Global 2000 as customers. The AI boom remains a major tailwind for the company. Elsewhere, it was a good day for many consumer-facing stocks. Dollar Tree, Best Buy, and Hormel are up 19%, 18%, and 13%, respectively, today after each stock reported earnings. I'd argue that these results are promising for the broader economy, especially after Walmart and Target's earnings last week showed that the U.S. consumer remains surprisingly..."}]},{"title":"Sticky PCE inflation data challenges Federal Reserve rate cut timeline","summary":"The April Personal Consumption Expenditures (PCE) price index rose 3.8% year-over-year, marking its fastest pace in three years. Despite being in line with many forecasts, the persistent inflationary pressure, fueled largely by energy costs, has led markets to anticipate that the Federal Reserve may maintain current interest rates for the rest of 2026.","stories":[{"url":"https://www.fool.com/coverage/stock-market-today/2026/05/28/stock-market-today-may-28-inflation-isn-t-stopping-this-stock-market-rally/","title":"Stock Market Today, May 28: Inflation Isn't Stopping This Stock Market Rally","publisher":"www.fool.com","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn2.gstatic.com/faviconV2?url=https://www.fool.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"Today, May 28, 2026, Snowflake's surge on robust earnings and a multibillion‑dollar Amazon pact helped tech lead U.S. stocks to fresh gains. By Emma Newbery – May 28, 2026 at 5:30PM EST. Summarize with AI. The S&P 500 (^GSPC +0.58%) rose 0.58% to 7,563.63, the Nasdaq Composite (^IXIC +0.91%) gained 0.91% to 26,917.47 as stocks reversed early losses to close near record highs despite hotter PCE inflation. The Dow Jones Industrial Average (^DJI +0.05%) inched up 0.05% to 50,668.97. Market movers. Snowflake jumped 36% after strong Q1 results and a $6 billion Amazon deal, while Microsoft climbed on analyst optimism and plans to build in‑house AI models. In contrast, Salesforce dipped despite yes..."},{"url":"https://www.investopedia.com/stock-market-today-dow-jones-s-and-p-500-05282026-11985218","title":"Markets News, May 28, 2026: Indexes Close at Fresh Records as ...","publisher":"www.investopedia.com","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn1.gstatic.com/faviconV2?url=https://www.investopedia.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"Iran War Pushed Up the Fed's Favorite Measure of Inflation in April. ... Surging energy prices due to the Iran war helped push the Federal Reserve's preferred inflation gauge to its highest in nearly three years in April. Consumer prices as measured by the Personal Consumption Expenditures price index rose 3.8% over 12 months in April, the highest annual inflation since May 2023, the Bureau of Economic Analysis said Thursday. That was in line with economists' expectations, though the 0.4% increase in the index from March was slightly below the 0.5% forecast by a survey of economists by Dow Jones Newswires and The Wall Street Journal. A 5.5% month-over-month surge in gasoline and other energy..."},{"url":"https://www.theguardian.com/business/2026/may/28/inflation-increased-april-iran-war-price-rises","title":"US inflation rose at fastest pace in three years in April as Iran war ...","publisher":"www.theguardian.com","image_url":null,"published_at":null,"favicon_url":"https://encrypted-tbn0.gstatic.com/faviconV2?url=https://www.theguardian.com&client=FINANCE_HUB&size=32&type=FAVICON&fallback_opts=TYPE,SIZE,URL","related_instruments":[],"snippet":"US inflation rose at fastest pace in three years in April as Iran war hikes up prices. Americans are growing frustrated with Trump's handling of the economy as cost of living soars ahead of midterms. Guardian staff and agencies. Thu 28 May 2026 12.06 EDT. US inflation increased at its fastest pace in three years in April, driven by higher energy prices amid the war with Iran, and cementing economists' views that the Federal Reserve could hold interest rates unchanged well into next year. Surging price pressures are eroding household income and could restrain consumer spending and economic growth this quarter. Income at the disposal of households after adjusting for inflation dropped for a th..."}]}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_summary","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/movers":{"get":{"tags":["Markets"],"operationId":"getMarketMovers","summary":"Market Movers","description":"Returns notable instruments and market-discovery groups.\n\nUse this for mover lists, discovery modules, market overview pages, and agents looking for securities worth further inspection.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Movers response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketMoversResponse"},"examples":{"success":{"summary":"Market Movers success","value":{"meta":{"provider":"google_finance","route":"market_movers","cache":"miss","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-28T21:59:32.592Z","request_id":"267f7671-b487-43d0-afb0-85ff155e4668","identity_tier":"anonymous"},"data":{"resource":"market_movers","instruments":[{"entity_id":"/g/11fxx4x3z2","symbol":"SNOW","exchange":"NYSE","name":"Snowflake Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":239.2,"change":63.940002,"change_percent":36.48294,"previous_close":175.26,"last_trade_time":"2026-05-28T21:58:35.000Z"},"extended_hours_quote":{"price":241.22,"change":2.0200043,"change_percent":0.8444834,"last_trade_time":"2026-05-28T20:00:07.000Z"}},{"entity_id":"/g/11dx9gdtq8","symbol":"RCAT","exchange":"NASDAQ","name":"Red Cat Holdings Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":14.15,"change":3.4799995,"change_percent":32.614803,"previous_close":10.67,"last_trade_time":"2026-05-28T21:59:09.000Z"},"extended_hours_quote":{"price":14.1788,"change":0.02880001,"change_percent":0.20353365,"last_trade_time":"2026-05-28T20:00:00.000Z"}},{"entity_id":"/g/11z3001sjk","symbol":"AVEX","exchange":"NYSE","name":"AEVEX Corp","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":40.48,"change":9.65,"change_percent":31.30068,"previous_close":30.83,"last_trade_time":"2026-05-28T21:55:18.000Z"},"extended_hours_quote":{"price":39.16,"change":-1.3199997,"change_percent":-3.2608688,"last_trade_time":"2026-05-28T20:00:02.000Z"}}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_movers","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/events":{"get":{"tags":["Markets"],"operationId":"getMarketEvents","summary":"Market Events","description":"Returns finance event data when available.\n\nUse this for event timelines, market calendars, earnings context, and agents that need date-based finance context.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Events response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketEventsResponse"},"examples":{"success":{"summary":"Market Events success","value":{"meta":{"provider":"google_finance","route":"market_events","cache":"kv","ttl_seconds":900,"stale_seconds":10800,"generated_at":"2026-05-28T21:59:33.013Z","request_id":"7a793839-a6d5-45fd-8c62-591b6937af6c","identity_tier":"anonymous"},"data":{"resource":"market_events","events":[{"symbol":"CM","exchange":"NYSE","date":"2026-05-28","title":"Q2 2026 Earnings Conference Call","category":"earnings_call","instrument":{"entity_id":"/g/11_yysp2m","symbol":"CM","exchange":"NYSE","name":"Canadian Imperial Bank of Commerce"},"earnings":{"fiscal_year":2026,"fiscal_quarter":2,"period_end":"2026-04-30","reported_at":"2026-05-28T11:30:00.000Z","currency":"CAD","revenue":8006000000,"revenue_estimate":7960000000,"eps":0,"eps_estimate":2.44809,"revenue_surprise_percent":0.005778894472361809,"eps_surprise_percent":0.037543554362788924}},{"symbol":"RY","exchange":"NYSE","date":"2026-05-28","title":"Q2 2026 Earnings Conference Call","category":"earnings_call","instrument":{"entity_id":"/m/07zljg4","symbol":"RY","exchange":"NYSE","name":"Royal Bank of Canada"},"earnings":{"fiscal_year":2026,"fiscal_quarter":2,"period_end":"2026-04-30","reported_at":"2026-05-28T12:30:00.000Z","currency":"CAD","revenue":17453000000,"revenue_estimate":17269785020,"eps":0,"eps_estimate":3.79036,"revenue_surprise_percent":0.010608990198072541,"eps_surprise_percent":0.028926012304899728}},{"symbol":"TD","exchange":"NYSE","date":"2026-05-28","title":"Q2 2026 Earnings Conference Call","category":"earnings_release","instrument":{"entity_id":"/m/07zkz_x","symbol":"TD","exchange":"NYSE","name":"The Toronto-Dominion Bank"},"earnings":{"fiscal_year":2026,"fiscal_quarter":2,"period_end":"2026-04-30","reported_at":"2026-05-28T13:30:00.000Z","currency":"CAD","revenue":14639000000,"revenue_estimate":14675000000,"eps":0,"eps_estimate":2.25914,"revenue_surprise_percent":-0.002453151618398637,"eps_surprise_percent":0.053498233841196195}}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_events","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/news":{"get":{"tags":["News"],"operationId":"getNews","summary":"News","description":"Returns a finance news feed.\n\nUse this for market-news modules, ticker-adjacent news, research workflows, and agents that need recent finance headlines.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":20},"description":"Maximum number of news items or stories to request. Alias: count."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"News response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsResponse"},"examples":{"success":{"summary":"News success","value":{"meta":{"provider":"google_finance","route":"news","cache":"miss","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-28T21:59:33.557Z","request_id":"a2f34142-20bf-433c-b49b-8957748656e8","identity_tier":"anonymous"},"data":{"resource":"news","stories":[]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"news","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/news/collections":{"get":{"tags":["News"],"operationId":"getNewsCollections","summary":"News Collections","description":"Returns finance story collections.\n\nUse this for story feeds, news cards, market-research context, and agents that need a compact set of current finance stories.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":50,"default":8},"description":"Maximum number of news items or stories to request. Alias: count."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"News Collections response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/NewsCollectionsResponse"},"examples":{"success":{"summary":"News Collections success","value":{"meta":{"provider":"google_finance","route":"news_collections","cache":"miss","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-28T21:59:36.445Z","request_id":"72831f2f-6be3-463c-a1fd-b44608896483","identity_tier":"anonymous"},"data":{"resource":"story_collections","collections":[{"title":"Virgin Galactic Stock Lifts Off After-Hours — Here's Why","summary":"SPCE stock rises as court approves settlement of shareholder lawsuits. Insurers to pay $2.75M, stock gains 14% in after-hours trading.","stories":[]},{"title":"American Eagle Flags Falling Sales in Core Women’s Category","summary":"\n            American Eagle Outfitters said its core brand isn’t performing as well as management would like, after the segment’s sales fell in the first quarter.\n        ","stories":[]}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"news_collections","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/markets/highlights":{"get":{"tags":["Markets"],"operationId":"getMarketHighlights","summary":"Market Highlights","description":"Returns featured market highlights and high-level market context.\n\nUse this for overview screens and agents that need a broad current-market entry point.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Market Highlights response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MarketHighlightsResponse"},"examples":{"success":{"summary":"Market Highlights success","value":{"meta":{"provider":"google_finance","route":"market_highlights","cache":"miss","ttl_seconds":60,"stale_seconds":720,"generated_at":"2026-05-28T21:59:37.039Z","request_id":"72137e1f-e2cd-4ad6-b6ad-72eaf1a0b0fa","identity_tier":"anonymous"},"data":{"resource":"market_highlights","instruments":[{"entity_id":"/m/0cqyw","symbol":".DJI","exchange":"INDEXDJX","name":"Dow Jones Industrial Average","currency":null,"country":null,"timezone":"America/New_York","quote":{"price":50668.97,"change":24.6875,"change_percent":0.048746865,"previous_close":50644.28,"last_trade_time":"2026-05-28T20:47:05.000Z"},"extended_hours_quote":null},{"entity_id":"/m/016yss","symbol":".INX","exchange":"INDEXSP","name":"S&P 500","currency":null,"country":null,"timezone":"America/New_York","quote":{"price":7563.63,"change":43.27002,"change_percent":0.5753717,"previous_close":7520.36,"last_trade_time":"2026-05-28T21:33:33.000Z"},"extended_hours_quote":null},{"entity_id":"/m/02853rl","symbol":".IXIC","exchange":"INDEXNASDAQ","name":"Nasdaq Composite","currency":null,"country":null,"timezone":"America/New_York","quote":{"price":26917.47,"change":242.73633,"change_percent":0.9099859,"previous_close":26674.734,"last_trade_time":"2026-05-28T21:15:57.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"market_highlights","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/quotes/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getQuote","summary":"Quote","description":"Returns a compact quote summary for one symbol.\n\nUse this for watchlists, symbol snapshots, portfolio rows, and agents that need current price, change, currency, exchange, and market-session context when available.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Quote response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteResponse"},"examples":{"success":{"summary":"Quote success","value":{"meta":{"provider":"google_finance","route":"quote","cache":"miss","ttl_seconds":30,"stale_seconds":360,"generated_at":"2026-05-28T21:59:37.660Z","request_id":"6ff704c6-d43f-4ca8-8b42-7034cdfde493","identity_tier":"anonymous"},"data":{"resource":"quote","instrument":{"entity_id":"/m/07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":312.51,"change":1.6600037,"change_percent":0.5340208,"previous_close":310.85,"last_trade_time":"2026-05-28T21:59:15.000Z"},"extended_hours_quote":{"price":312.35,"change":-0.16000366,"change_percent":-0.051199533,"last_trade_time":"2026-05-28T20:00:01.000Z"}},"instruments":[{"entity_id":"/m/07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":312.51,"change":1.6600037,"change_percent":0.5340208,"previous_close":310.85,"last_trade_time":"2026-05-28T21:59:15.000Z"},"extended_hours_quote":{"price":312.35,"change":-0.16000366,"change_percent":-0.051199533,"last_trade_time":"2026-05-28T20:00:01.000Z"}}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"quote","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/quotes/{symbol}/details":{"get":{"tags":["Quotes"],"operationId":"getQuoteDetails","summary":"Quote Details","description":"Returns expanded quote details for one symbol.\n\nUse this for quote pages, instrument drilldowns, richer dashboards, and agents that need more detail than the compact quote summary.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Quote Details response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteDetailsResponse"},"examples":{"success":{"summary":"Quote Details success","value":{"meta":{"provider":"google_finance","route":"quote_details","cache":"miss","ttl_seconds":60,"stale_seconds":720,"generated_at":"2026-05-28T21:59:38.340Z","request_id":"fd167ec9-b893-4605-8362-bd65cd9d8d2e","identity_tier":"anonymous"},"data":{"resource":"quote_details","instrument":{"entity_id":"/m/07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":312.51,"change":1.6600037,"change_percent":0.5340208,"previous_close":310.85,"last_trade_time":"2026-05-28T21:59:15.000Z"},"extended_hours_quote":{"price":312.35,"change":-0.16000366,"change_percent":-0.051199533,"last_trade_time":"2026-05-28T20:00:01.000Z"}},"instruments":[{"entity_id":"/m/07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":312.51,"change":1.6600037,"change_percent":0.5340208,"previous_close":310.85,"last_trade_time":"2026-05-28T21:59:15.000Z"},"extended_hours_quote":{"price":312.35,"change":-0.16000366,"change_percent":-0.051199533,"last_trade_time":"2026-05-28T20:00:01.000Z"}}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"quote_details","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/quotes/{symbol}/profile":{"get":{"tags":["Quotes"],"operationId":"getQuoteProfile","summary":"Instrument Profile","description":"Returns entity-level detail for one quote symbol.\n\nUse this for company or instrument profile sections and workflows that need metadata around a finance entity.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Instrument Profile response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteProfileResponse"},"examples":{"success":{"summary":"Quote Profile success","value":{"meta":{"provider":"google_finance","route":"quote_profile","cache":"miss","ttl_seconds":60,"stale_seconds":720,"generated_at":"2026-05-28T21:59:38.994Z","request_id":"399c5deb-0832-40f0-aed2-915db0bbf480","identity_tier":"anonymous"},"data":{"resource":"quote_profile","instrument":null,"instruments":[]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"quote_profile","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/prices/{symbol}/history":{"get":{"tags":["Quotes"],"operationId":"getPricesHistory","summary":"Price History","description":"Returns historical pricing data for one symbol.\n\nUse this for charts, trend views, return calculations, and agents that need recent or historical price movement context.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Price History response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PricesHistoryResponse"},"examples":{"success":{"summary":"Prices History success","value":{"meta":{"provider":"google_finance","route":"prices_history","cache":"miss","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-28T21:59:39.630Z","request_id":"45a8554b-acbb-4d5a-a4f6-0d1a7534d83e","identity_tier":"anonymous"},"data":{"resource":"prices_history","instrument":{"symbol":"AAPL","exchange":"NASDAQ","entity_id":"/m/07zmbvf","name":"Apple Inc"},"currency":"USD","timezone_offset_seconds":-14400,"previous_close":310.85,"prices":[{"timestamp":"2026-05-28T13:30:00.000Z","price":310.68,"change":-0.17000000000001592,"change_percent":-0.0005468875663503809,"volume":10288},{"timestamp":"2026-05-28T13:31:00.000Z","price":310.04,"change":-0.8100000000000023,"change_percent":-0.0026057584043751077,"volume":906438},{"timestamp":"2026-05-28T13:32:00.000Z","price":310.08,"change":-0.7700000000000387,"change_percent":-0.0024770789769986766,"volume":186692}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"prices_history","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/financials/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getFinancials","summary":"Financials","description":"Returns financial data for one symbol when available.\n\nUse this for company financial sections, valuation workflows, screening inputs, and research agents.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Financials response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FinancialsResponse"},"examples":{"success":{"summary":"Financials success","value":{"meta":{"provider":"google_finance","route":"financials","cache":"edge","ttl_seconds":21600,"stale_seconds":259200,"generated_at":"2026-05-28T21:59:40.054Z","request_id":"e796787d-b9a7-4982-a150-6f5d319b9400","identity_tier":"anonymous"},"data":{"resource":"financials","instrument":{"entity_id":"/m/07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc"},"quarterly":[{"fiscal_year":2026,"fiscal_quarter":2,"period":"quarter","current":{"revenue":111184000000,"net_income":29578000000,"eps":2.01,"net_margin_percent":26.6,"operating_income":35885000000,"revenue_estimate":109578690550,"eps_estimate":1.94136,"revenue_surprise_percent":0.014649832389332198,"eps_surprise_percent":0.03535665718877478,"currency":"USD","period_end":"2026-03-28","gross_margin_percent":48.51},"year_ago":{"revenue":95359000000,"net_income":24780000000,"eps":1.65,"net_margin_percent":25.99,"operating_income":29589000000,"revenue_estimate":94706676660,"eps_estimate":1.62555,"revenue_surprise_percent":0.0068878284298989996,"eps_surprise_percent":0.015041063024822282,"currency":"USD","period_end":"2025-03-29","gross_margin_percent":45.03}},{"fiscal_year":2026,"fiscal_quarter":1,"period":"quarter","current":{"revenue":143756000000,"net_income":42097000000,"eps":2.84,"net_margin_percent":29.28,"operating_income":50852000000,"revenue_estimate":138522147180,"eps_estimate":2.67304,"revenue_surprise_percent":0.0377835091828238,"eps_surprise_percent":0.06246071888187233,"currency":"USD","period_end":"2025-12-27","gross_margin_percent":69.7},"year_ago":{"revenue":124300000000,"net_income":36330000000,"eps":2.4,"net_margin_percent":29.23,"operating_income":42832000000,"revenue_estimate":124026505760,"eps_estimate":2.34685,"revenue_surprise_percent":0.0022051273501910193,"eps_surprise_percent":0.022647378400835177,"currency":"USD","period_end":"2024-12-28","gross_margin_percent":63.07}},{"fiscal_year":2025,"fiscal_quarter":4,"period":"quarter","current":{"revenue":102466000000,"net_income":27466000000,"eps":1.84,"net_margin_percent":26.8,"operating_income":32427000000,"revenue_estimate":102250480070,"eps_estimate":1.77112,"revenue_surprise_percent":0.002107764480445045,"eps_surprise_percent":0.03889064546727497,"currency":"USD","period_end":"2025-09-27","gross_margin_percent":45.85},"year_ago":{"revenue":94930000000,"net_income":14736000000,"eps":0.96,"net_margin_percent":15.52,"operating_income":29591000000,"revenue_estimate":94415830760,"eps_estimate":1.60349,"revenue_surprise_percent":0.0054457947979824565,"eps_surprise_percent":-0.4013059015023481,"currency":"USD","period_end":"2024-09-28","gross_margin_percent":43.01}}],"annual":[{"fiscal_year":2025,"period":"annual","current":{"revenue":416161000000,"net_income":112010000000,"eps":7.46,"net_margin_percent":26.91,"operating_income":133050000000,"revenue_estimate":415655411720,"eps_estimate":7.39101,"revenue_surprise_percent":0.0012163640018732198,"eps_surprise_percent":0.009334312901755015,"currency":"USD","period_end":"2025-09-27","gross_margin_percent":45.93},"year_ago":{"revenue":391035000000,"net_income":93736000000,"eps":6.08,"net_margin_percent":23.97,"operating_income":123216000000,"revenue_estimate":390538800140,"eps_estimate":6.69694,"revenue_surprise_percent":0.001270552016399197,"eps_surprise_percent":-0.0921226709512105,"currency":"USD","period_end":"2024-09-28","gross_margin_percent":42.54}},{"fiscal_year":2024,"period":"annual","current":{"revenue":391035000000,"net_income":93736000000,"eps":6.08,"net_margin_percent":23.97,"operating_income":123216000000,"revenue_estimate":390538800140,"eps_estimate":6.69694,"revenue_surprise_percent":0.001270552016399197,"eps_surprise_percent":-0.0921226709512105,"currency":"USD","period_end":"2024-09-28","gross_margin_percent":42.54},"year_ago":{"revenue":383285000000,"net_income":96995000000,"eps":6.13,"net_margin_percent":25.31,"operating_income":114301000000,"revenue_estimate":382909841620,"eps_estimate":6.07131,"revenue_surprise_percent":0.0009797564314690753,"eps_surprise_percent":0.009666777021762924,"currency":"USD","period_end":"2023-09-30","gross_margin_percent":38.7}},{"fiscal_year":2023,"period":"annual","current":{"revenue":383285000000,"net_income":96995000000,"eps":6.13,"net_margin_percent":25.31,"operating_income":114301000000,"revenue_estimate":382909841620,"eps_estimate":6.07131,"revenue_surprise_percent":0.0009797564314690753,"eps_surprise_percent":0.009666777021762924,"currency":"USD","period_end":"2023-09-30","gross_margin_percent":38.7},"year_ago":{"revenue":394328000000,"net_income":99803000000,"eps":6.11,"net_margin_percent":25.31,"operating_income":119437000000,"revenue_estimate":392778994500,"eps_estimate":6.10809,"revenue_surprise_percent":0.003943707585411622,"eps_surprise_percent":0.00031270004207543153,"currency":"USD","period_end":"2022-09-24","gross_margin_percent":39}}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"financials","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/earnings/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getEarnings","summary":"Earnings","description":"Returns earnings data for one symbol when available.\n\nUse this for earnings sections, upcoming/reporting context, and agents that need earnings history or expectations.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Earnings response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EarningsResponse"},"examples":{"success":{"summary":"Earnings success","value":{"meta":{"provider":"google_finance","route":"earnings","cache":"miss","ttl_seconds":900,"stale_seconds":10800,"generated_at":"2026-05-28T21:59:40.418Z","request_id":"52eb5b30-10dc-4734-afed-9b892f68bf39","identity_tier":"anonymous"},"data":{"resource":"earnings","instrument":{"entity_id":"/m/07zmbvf","symbol":"AAPL","exchange":"NASDAQ","name":"Apple Inc"},"earnings":[{"fiscal_year":2026,"fiscal_quarter":2,"period_end":"2026-03-31","reported_at":"2026-04-30T21:00:00.000Z","currency":"USD","revenue":111184000000,"revenue_estimate":109578690550,"eps":2.01,"eps_estimate":1.94136,"revenue_surprise_percent":0.014649832389332198,"eps_surprise_percent":0.03535665718877478},{"fiscal_year":2026,"fiscal_quarter":3,"period_end":"2026-06-30","reported_at":"2026-07-30T21:00:00.000Z","currency":"USD","revenue":0,"revenue_estimate":109015606590,"eps":0,"eps_estimate":1.89541,"revenue_surprise_percent":0,"eps_surprise_percent":0},{"fiscal_year":2026,"fiscal_quarter":4,"period_end":"2026-09-30","reported_at":null,"currency":"USD","revenue":0,"revenue_estimate":114207466420,"eps":0,"eps_estimate":2.01074,"revenue_surprise_percent":0,"eps_surprise_percent":0}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"earnings","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/related/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getRelatedAssets","summary":"Related Assets","description":"Returns entities related to one symbol.\n\nUse this for peer discovery, comparable-company lists, related-instrument widgets, and agents expanding from one ticker to nearby instruments.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Related Assets response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RelatedAssetsResponse"},"examples":{"success":{"summary":"Related Assets success","value":{"meta":{"provider":"google_finance","route":"related_assets","cache":"miss","ttl_seconds":3600,"stale_seconds":43200,"generated_at":"2026-05-28T21:59:41.071Z","request_id":"b307e31d-a302-43df-95b2-8d5c77fbacf2","identity_tier":"anonymous"},"data":{"resource":"related_assets","instrument":{"entity_id":"/m/07zl90k","symbol":"AMZN","exchange":"NASDAQ","name":"Amazon.com Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":274,"change":2.149994,"change_percent":0.7908751,"previous_close":271.85,"last_trade_time":"2026-05-28T21:59:24.000Z"},"extended_hours_quote":{"price":273.5,"change":-0.5,"change_percent":-0.18248175,"last_trade_time":"2026-05-28T20:00:01.000Z"}},"instruments":[{"entity_id":"/m/07zl90k","symbol":"AMZN","exchange":"NASDAQ","name":"Amazon.com Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":274,"change":2.149994,"change_percent":0.7908751,"previous_close":271.85,"last_trade_time":"2026-05-28T21:59:24.000Z"},"extended_hours_quote":{"price":273.5,"change":-0.5,"change_percent":-0.18248175,"last_trade_time":"2026-05-28T20:00:01.000Z"}},{"entity_id":"/m/07zln_9","symbol":"MSFT","exchange":"NASDAQ","name":"Microsoft Corp","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":426.99,"change":14.319977,"change_percent":3.4700794,"previous_close":412.67,"last_trade_time":"2026-05-28T21:59:25.000Z"},"extended_hours_quote":{"price":427.5,"change":0.51000977,"change_percent":0.11944303,"last_trade_time":"2026-05-28T20:00:01.000Z"}},{"entity_id":"/m/0ckhqlx","symbol":"TSLA","exchange":"NASDAQ","name":"Tesla Inc","currency":"USD","country":"US","timezone":"America/New_York","quote":{"price":442.1,"change":1.7400208,"change_percent":0.39513597,"previous_close":440.36,"last_trade_time":"2026-05-28T21:59:28.000Z"},"extended_hours_quote":{"price":441.5451,"change":-0.5549011,"change_percent":-0.12551485,"last_trade_time":"2026-05-28T20:00:00.000Z"}}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"related_assets","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/sentiment/{symbol}":{"get":{"tags":["Quotes"],"operationId":"getSentiment","summary":"Sentiment","description":"Returns sentiment-oriented data for one symbol when available.\n\nUse this as one input to research pages, ticker summaries, and agents that combine sentiment with price, news, and fundamentals.","parameters":[{"name":"symbol","in":"path","required":true,"schema":{"type":"string"},"description":"Ticker or finance symbol path segment, for example AAPL."},{"name":"exchange","in":"query","required":false,"schema":{"type":"string","default":"NASDAQ"},"description":"Exchange hint used with the symbol when the ticker is ambiguous, for example NASDAQ, NYSE, or INDEXNASDAQ."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Sentiment response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SentimentResponse"},"examples":{"success":{"summary":"Sentiment success","value":{"meta":{"provider":"google_finance","route":"sentiment","cache":"miss","ttl_seconds":3600,"stale_seconds":43200,"generated_at":"2026-05-28T21:59:41.662Z","request_id":"0174bf0f-d409-4de0-b7e5-d42e19fc8383","identity_tier":"anonymous"},"data":{"resource":"sentiment","instrument":null,"instruments":[]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Symbol routes require a symbol path segment, for example /v1/quotes/AAPL.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"sentiment","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/realtime/quotes":{"get":{"tags":["Realtime"],"operationId":"getRealtimeQuotes","summary":"Realtime Quotes","description":"Returns realtime price snapshots for finance entities.\n\nUse this for live tiles, compact price boards, monitoring screens, and agents that need current entity snapshots.","parameters":[{"name":"entity_ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated finance entity IDs. Omit to use the default market pair."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Realtime Quotes response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeQuotesResponse"},"examples":{"success":{"summary":"Realtime Quotes success","value":{"meta":{"provider":"google_finance","route":"realtime_quotes","cache":"miss","ttl_seconds":5,"stale_seconds":305,"generated_at":"2026-05-28T21:59:42.279Z","request_id":"233dd619-892f-4e11-880b-67ebabd7c119","identity_tier":"anonymous"},"data":{"resource":"realtime_quotes","instrument":null,"instruments":[]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"realtime_quotes","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/realtime/trends":{"get":{"tags":["Realtime"],"operationId":"getRealtimeTrends","summary":"Realtime Trends","description":"Returns realtime trend-line data for finance entities.\n\nUse this for small live charts, intraday movement modules, and agents that need compact trend context.","parameters":[{"name":"entity_ids","in":"query","required":false,"schema":{"type":"string"},"description":"Comma-separated finance entity IDs. Omit to use the default market pair."},{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Realtime Trends response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RealtimeTrendsResponse"},"examples":{"success":{"summary":"Realtime Trends success","value":{"meta":{"provider":"google_finance","route":"realtime_trends","cache":"miss","ttl_seconds":15,"stale_seconds":315,"generated_at":"2026-05-28T21:59:42.947Z","request_id":"12874160-be26-4073-8dc7-c092375ae4a3","identity_tier":"anonymous"},"data":{"resource":"realtime_trends","instrument":null,"currency":null,"timezone_offset_seconds":null,"previous_close":null,"prices":[]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"realtime_trends","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}},"/v1/watchlists":{"get":{"tags":["User Context"],"operationId":"getWatchlists","summary":"Watchlists","description":"Returns watchlist-context data when available for the request context.\n\nAnonymous requests may return empty or limited data. Use this only when a workflow can tolerate account-context availability differences.","parameters":[{"name":"X-Gfin-Contact","in":"header","required":false,"schema":{"type":"string"},"description":"Stable contact identity for higher public request limits, for example an email address or service name."},{"name":"X-Gfin-Key","in":"header","required":false,"schema":{"type":"string"},"description":"API key for higher-volume access. Authorization: Bearer is also supported."}],"responses":{"200":{"description":"Watchlists response.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"x-gfin-cache":{"description":"Cache state for this response.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WatchlistsResponse"},"examples":{"success":{"summary":"Watchlists success","value":{"meta":{"provider":"google_finance","route":"watchlists","cache":"miss","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-28T21:59:43.572Z","request_id":"c85e7485-7327-4112-b2dc-ce754e2a7ed8","identity_tier":"anonymous"},"data":{"resource":"watchlists","instruments":[{"entity_id":"/g/11fjx5yc5c","symbol":"SIXI","exchange":"INDEXCBOE","name":"Industrials","currency":null,"country":null,"timezone":"America/Chicago","quote":{"price":1751.64,"change":-4.75,"change_percent":-0.2704411,"previous_close":1756.39,"last_trade_time":"2026-05-28T20:47:05.000Z"},"extended_hours_quote":null},{"entity_id":"/g/11fjx6260j","symbol":"SIXM","exchange":"INDEXCBOE","name":"Financials","currency":null,"country":null,"timezone":"America/Chicago","quote":{"price":631.47,"change":-1.8000488,"change_percent":-0.28424665,"previous_close":633.27,"last_trade_time":"2026-05-28T20:47:07.000Z"},"extended_hours_quote":null},{"entity_id":"/g/11h026r6m1","symbol":"SIXC","exchange":"INDEXCBOE","name":"Communications","currency":null,"country":null,"timezone":"America/Chicago","quote":{"price":609.66,"change":1.9699707,"change_percent":0.32417363,"previous_close":607.69,"last_trade_time":"2026-05-28T20:47:07.000Z"},"extended_hours_quote":null}]}}}}}}},"400":{"description":"Invalid request parameters.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"bad_request":{"summary":"Invalid request","value":{"error":{"code":"bad_request","message":"Invalid request parameters.","next_action":"fix_request","request_id":"req_example"}}}}}}},"401":{"description":"The supplied API key is invalid.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"invalid_api_key":{"summary":"Invalid API key","value":{"error":{"code":"invalid_api_key","message":"The supplied gfin API key is not valid.","next_action":"fix_auth","request_id":"req_example"}}}}}}},"404":{"description":"Unknown route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"not_found":{"summary":"Unknown route","value":{"error":{"code":"not_found","message":"Unknown gfin route. Use /v1/routes or /v1/openapi.json to inspect supported routes.","next_action":"inspect_error","request_id":"req_example"}}},"route_not_found":{"summary":"Unknown route","value":{"error":{"code":"route_not_found","message":"This gfin route is not available.","next_action":"choose_supported_route","request_id":"req_example"}}}}}}},"405":{"description":"HTTP method is not allowed for this route.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"method_not_allowed":{"summary":"Method not allowed","value":{"error":{"code":"method_not_allowed","message":"gfin v1 exposes read-only GET routes.","next_action":"inspect_error","request_id":"req_example"}}}}}}},"429":{"description":"Request limit exceeded. Retry-After is included.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before retrying.","schema":{"type":"integer","minimum":1}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/RateLimitResponse"},"examples":{"rate_limited":{"summary":"Request limit exceeded","value":{"error":{"code":"rate_limited","message":"Request budget exhausted.","next_action":"retry_after","request_id":"req_example"},"rate_limit":{"scope":"request","tier":"anonymous","reason":"rate_limited","retry_after_seconds":42,"limit":1200,"remaining":0,"reset_at":"2026-05-05T18:33:00.000Z","upgrade":"Send X-Gfin-Contact for higher no-key limits; email sam@gfin.dev for an API key."}}}}}}},"502":{"description":"The data request could not be completed.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_response_error":{"summary":"Data source response error","value":{"meta":{"provider":"google_finance","route":"watchlists","cache":"kv","ttl_seconds":300,"stale_seconds":3600,"generated_at":"2026-05-05T18:32:52.359Z","request_id":"req_example","identity_tier":"anonymous"},"error":{"code":"data_source_response_error","message":"The data source returned an unusable response for this finance data request.","next_action":"retry_or_use_cached_response","request_id":"req_example"}}},"response_too_large":{"summary":"Response too large","value":{"error":{"code":"response_too_large","message":"The finance data response exceeded gfin's configured response-size cap.","next_action":"narrow_request","request_id":"req_example"}}}}}}},"504":{"description":"The data source timed out or could not be reached.","headers":{"x-gfin-request-id":{"description":"Request ID for logs and support.","schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"examples":{"data_source_unavailable":{"summary":"Data source unavailable","value":{"error":{"code":"data_source_unavailable","message":"The data source could not be reached in time.","next_action":"retry_with_backoff","request_id":"req_example"}}}}}}}}}}},"externalDocs":{"description":"Google Finance source docs","url":"https://bluedoor.sh/apis/financial-data/sources/gfin"}}