> ## Documentation Index
> Fetch the complete documentation index at: https://socialquery.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Option Chains

> One complete current Yahoo-listed option expiry, with calls and puts flattened into option_contract records. Verifies the nearest chain and available expiries before fetching an explicit expiry; unlisted dates return a free empty list. Delayed quotes, not execution-grade data. Bounded to 10,000 contracts and 4 MiB; incomplete responses fail without charging.

Get one complete current Yahoo-listed expiry as a flat list of `option_contract` records: calls followed by puts, with the source order retained within each side. No strikes are silently filtered or sampled. Each record preserves the contract symbol, strike, expiry, bid/ask, last price, price changes, volume, open interest, implied volatility, moneyness, contract-size classification, currency and last-trade time. Missing optional market values stay `null`; source zero values stay zero.

`keyword` is one Yahoo ticker symbol, case-insensitive. For `AAPL:US`, the colon suffix is ignored; Yahoo symbols such as `BRK-B` or `7203.T` retain their own suffixes. `expiry` is an optional real `YYYY-MM-DD` date. Without it, the source's nearest listed expiry is used.

The first source read checks the nearest complete chain and its available-expiry list. An explicit listed date uses a second read when necessary. If the date is not listed, the response contains an empty list and costs zero credits. A failed or partial source response is never interpreted as an empty chain. Unknown instruments or instruments without corroborated option data can fail without charge; no unrelated symbol is substituted.

`total` and `returned_count` count the returned contracts for that expiry. `available_expiries` lists the source's current expiry choices. No cursor is needed because one successful response contains the entire selected chain. The adapter allows up to **10,000 contracts**, 250 expiry choices and a **4 MiB source response**. Larger, malformed or partial payloads fail without charging. Contract expiry, call/put marker, strike encoding and duplicate identities are validated. Adjusted native contract roots are preserved after corporate actions.

Quotes are delayed, commonly by about 15 minutes, and individual contracts can have stale last trades. `underlying_quote_time` and `underlying_delay_minutes` describe the underlying stock quote; they are not a guaranteed timestamp or delay for each option. This is not historical chain reconstruction or an execution-grade market feed.

The bounded provider runs use the existing configured allowance, pinned build, limited permissions, up to a 40-second run timeout and 45-second request deadline per read, within a single 55-second overall budget. A slow first read reduces the second read’s remaining allowance. At most two runs and ten source runs/minute are allowed. No Yahoo account cookies or user credentials are required.

A fresh nonempty response uses the catalog price shown above. Empty results, errors, cache hits and identical successful replays cost zero. Set `X-Max-Credits` to the listed credit price before calling.


## OpenAPI

````yaml GET /finance/options
openapi: 3.1.0
info:
  title: SocialQuery API
  version: '2026-10-09'
  description: >-
    Documented requests for public-source records. Inspect accepted inputs and
    credit amounts, then verify the selected operation before integrating
    preview coverage.
servers:
  - url: https://socialquery.dev/v1
security:
  - apiKey: []
paths:
  /finance/options:
    get:
      tags:
        - Finance
      summary: Finance Options
      description: >-
        One complete current Yahoo-listed option expiry, with calls and puts
        flattened into option_contract records. Verifies the nearest chain and
        available expiries before fetching an explicit expiry; unlisted dates
        return a free empty list. Delayed quotes, not execution-grade data.
        Bounded to 10,000 contracts and 4 MiB; incomplete responses fail without
        charging.
      operationId: get_finance_options
      parameters:
        - name: keyword
          in: query
          required: true
          example: AAPL
          schema:
            type: string
          description: >-
            Yahoo ticker symbol, case-insensitive. A colon exchange suffix is
            ignored; international Yahoo suffixes are preserved. One symbol per
            call.
        - name: expiry
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Real YYYY-MM-DD date. Defaults to the source’s nearest listed
            expiry. A date absent from the corroborated current available-expiry
            list returns an empty list.
        - name: Cache-Control
          in: header
          required: false
          example: no-cache
          schema:
            type: string
        - name: Idempotency-Key
          in: header
          required: false
          example: 7a5e1b4c-2d8f-4a3b-9c1e-6e8b4d2a1f3c
          schema:
            type: string
        - name: X-Max-Credits
          in: header
          required: false
          description: >-
            Optional nonnegative integer cap on the maximum request hold. A live
            request whose hold exceeds this cap returns 422
            CREDIT_BUDGET_EXCEEDED before spending. Metered holds use the
            requested limit; cache hits and successful idempotent replays cost
            zero.
          schema:
            type: integer
            minimum: 0
      responses:
        '200':
          description: >-
            One complete current Yahoo-listed option expiry, with calls and puts
            flattened into option_contract records. Verifies the nearest chain
            and available expiries before fetching an explicit expiry; unlisted
            dates return a free empty list. Delayed quotes, not execution-grade
            data. Bounded to 10,000 contracts and 4 MiB; incomplete responses
            fail without charging.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            maxItems: 10000
                            items:
                              type: object
                              properties:
                                option_contract:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    symbol:
                                      type: string
                                    contract_symbol:
                                      type: string
                                    expiry:
                                      type: string
                                    contract_size:
                                      type: string
                                    currency:
                                      type: string
                                    type:
                                      type: string
                                      enum:
                                        - call
                                        - put
                                    strike:
                                      type: number
                                      minimum: 0
                                    last_price:
                                      type:
                                        - number
                                        - 'null'
                                    bid:
                                      type:
                                        - number
                                        - 'null'
                                    ask:
                                      type:
                                        - number
                                        - 'null'
                                    change:
                                      type:
                                        - number
                                        - 'null'
                                    percent_change:
                                      type:
                                        - number
                                        - 'null'
                                    implied_volatility:
                                      type:
                                        - number
                                        - 'null'
                                    volume:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    open_interest:
                                      type:
                                        - integer
                                        - 'null'
                                      minimum: 0
                                    in_the_money:
                                      type: boolean
                                    last_trade_date:
                                      type:
                                        - string
                                        - 'null'
                                  required:
                                    - id
                                    - symbol
                                    - contract_symbol
                                    - expiry
                                    - contract_size
                                    - currency
                                    - type
                                    - strike
                                    - last_price
                                    - bid
                                    - ask
                                    - change
                                    - percent_change
                                    - implied_volatility
                                    - volume
                                    - open_interest
                                    - in_the_money
                                    - last_trade_date
                              required:
                                - option_contract
                          total:
                            type: integer
                            minimum: 0
                          returned_count:
                            type: integer
                            minimum: 0
                          dropped:
                            type: integer
                            const: 0
                          symbol:
                            type: string
                          expiry:
                            type: string
                            format: date
                          available_expiries:
                            type: array
                            maxItems: 250
                            items:
                              type: string
                              format: date
                          underlying_price:
                            type: number
                            minimum: 0
                          underlying_currency:
                            type: string
                          underlying_quote_time:
                            type: string
                            format: date-time
                          underlying_delay_minutes:
                            type:
                              - integer
                              - 'null'
                            minimum: 0
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - total
                          - returned_count
                          - dropped
                          - symbol
                          - expiry
                          - available_expiries
                          - underlying_price
                          - underlying_currency
                          - underlying_quote_time
                          - underlying_delay_minutes
                          - source
                          - coverage_note
        '400':
          $ref: '#/components/responses/Error400'
        '401':
          $ref: '#/components/responses/Error401'
        '402':
          $ref: '#/components/responses/Error402'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '405':
          $ref: '#/components/responses/Error405'
        '409':
          $ref: '#/components/responses/Error409'
        '422':
          $ref: '#/components/responses/Error422'
        '429':
          $ref: '#/components/responses/Error429'
        '500':
          $ref: '#/components/responses/Error500'
        '502':
          $ref: '#/components/responses/Error502'
        '503':
          $ref: '#/components/responses/Error503'
        '504':
          $ref: '#/components/responses/Error504'
components:
  schemas:
    SocialQueryResponse:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - data
      properties:
        success:
          type: boolean
          const: true
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        data:
          type: object
          additionalProperties: true
          description: >-
            The selected operation determines the resource fields in this
            object. Source data can omit a metric or report it as null.
    SocialQueryError:
      type: object
      required:
        - success
        - platform
        - endpoint
        - credits_used
        - credits_remaining
        - request_id
        - cached
        - error
      properties:
        success:
          type: boolean
          const: false
        platform:
          type: string
        endpoint:
          type: string
        credits_used:
          type: integer
          minimum: 0
        credits_remaining:
          type:
            - integer
            - 'null'
        request_id:
          type: string
        cached:
          type: boolean
        error:
          type: object
          required:
            - code
            - type
            - message
            - status
            - doc_url
          properties:
            code:
              type: string
            type:
              type: string
            message:
              type: string
            status:
              type: integer
            doc_url:
              type: string
              format: uri
  responses:
    Error400:
      description: Upstream rejected the request.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error401:
      description: Missing, expired, invalid, or revoked API key.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error402:
      description: Insufficient SocialQuery credits.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error403:
      description: Key scope or provider policy denied access.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error404:
      description: Endpoint or upstream resource not found.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error405:
      description: HTTP method is not supported.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error409:
      description: Idempotency conflict or request in progress.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error422:
      description: Invalid parameters.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error429:
      description: Request limit reached.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error500:
      description: Request processing failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error502:
      description: Upstream service failed.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error503:
      description: Provider or required service is unavailable.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
    Error504:
      description: Upstream service timed out.
      headers:
        X-Request-Id:
          schema:
            type: string
        X-Credits-Used:
          schema:
            type: integer
        X-Credits-Remaining:
          schema:
            type: string
        X-Cache:
          schema:
            type: string
            enum:
              - HIT
              - MISS
              - BYPASS
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/SocialQueryError'
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.