> ## 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.

# Ticker Trading Summary

> Aggregate the complete corroborated Capitol Trades history for one ticker. Up to 1,000 indexed disclosures; incomplete, changing or oversized histories fail without charging. Values are estimates and coverage is approximately three years, not lifetime government records. Unknown identities return an unmatched zero-credit summary.

`keyword` resolves exactly to the source ticker, case-insensitively. A bare ticker defaults to `:US`; an explicit two-letter market suffix is preserved. Incomplete or ambiguous issuer resolution fails without charge. `unique_politicians` counts native member IDs. `top_politicians` contains up to ten members, ranked by disclosure count with stable member-ID ties, with each member's buy/sell counts. `buy_sell_ratio` is `null` when there are no sells, rather than an infinite or fabricated ratio.

Every successful aggregate reads **all currently indexed disclosures for the resolved identity**, up to **1,000 disclosures** in pages of 100. It never reports a sampled page as a full summary. A larger history, incomplete page, duplicate trade, conflicting identity, changed page total or malformed row fails without charging. Multiple pages use at most three concurrent reads, and the first page is fetched again to detect movement during collection. The source does not offer an atomic historical snapshot; edits away from that checked page can still occur.

`total_trades` includes buys, sells, exchanges and received assets. `buy_count` and `sell_count` cover those exact transaction types; `other_count` retains the rest. `total_value` sums the source's estimated values, and `avg_value` is the mean estimate. These are not exact disclosed dollar amounts. `earliest_trade_date` and `latest_trade_date` use **publication timestamps**, matching the disclosure index, rather than transaction-day fields. A historical filing retains the chamber on that filing even if the member's current source profile lists a different chamber.

Coverage is the public Capitol Trades index, approximately the past three years, not lifetime history or a complete government filing archive. The adapter has a **55-second overall deadline**, bounded source payloads and a shared **30-source-read/minute** ceiling. Failed or oversized histories are never silently truncated. The public issuer lookup receives no private credential; Firecrawl receives only its existing configured key.

An identity absent from a complete corroborated lookup returns `matched: false`, zero counts, null identity/average/date fields and empty top lists. This costs zero credits. Source errors do not become unmatched results. A fresh nonempty complete summary costs the catalog price above, irrespective of its page count. Cached responses, successful idempotent replays and errors cost zero. Set `X-Max-Credits` before calling to enforce a request cap.


## OpenAPI

````yaml GET /us_congress_trades/ticker
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:
  /us_congress_trades/ticker:
    get:
      tags:
        - Us Congress Trades
      summary: Us Congress Trades Ticker
      description: >-
        Aggregate the complete corroborated Capitol Trades history for one
        ticker. Up to 1,000 indexed disclosures; incomplete, changing or
        oversized histories fail without charging. Values are estimates and
        coverage is approximately three years, not lifetime government records.
        Unknown identities return an unmatched zero-credit summary.
      operationId: get_us_congress_trades_ticker
      parameters:
        - name: keyword
          in: query
          required: true
          example: AAPL
          schema:
            type: string
          description: >-
            Exact source ticker, case-insensitive. A bare symbol defaults to
            :US; an explicit two-letter market suffix is preserved.
        - 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: >-
            Aggregate the complete corroborated Capitol Trades history for one
            ticker. Up to 1,000 indexed disclosures; incomplete, changing or
            oversized histories fail without charging. Values are estimates and
            coverage is approximately three years, not lifetime government
            records. Unknown identities return an unmatched zero-credit summary.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          matched:
                            type: boolean
                          total_trades:
                            type: integer
                            minimum: 0
                          buy_count:
                            type: integer
                            minimum: 0
                          sell_count:
                            type: integer
                            minimum: 0
                          other_count:
                            type: integer
                            minimum: 0
                          total_value:
                            type: integer
                            minimum: 0
                          avg_value:
                            type:
                              - number
                              - 'null'
                          latest_trade_date:
                            type:
                              - string
                              - 'null'
                          earliest_trade_date:
                            type:
                              - string
                              - 'null'
                          source:
                            type: string
                          coverage_note:
                            type: string
                          ticker:
                            type:
                              - string
                              - 'null'
                          source_ticker:
                            type:
                              - string
                              - 'null'
                          issuer_name:
                            type:
                              - string
                              - 'null'
                          buy_sell_ratio:
                            type:
                              - number
                              - 'null'
                          unique_politicians:
                            type: integer
                            minimum: 0
                          top_politicians:
                            type: array
                            maxItems: 10
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                name:
                                  type: string
                                party:
                                  type: string
                                count:
                                  type: integer
                                  minimum: 0
                                buy_count:
                                  type: integer
                                  minimum: 0
                                sell_count:
                                  type: integer
                                  minimum: 0
                              required:
                                - id
                                - name
                                - party
                                - count
                                - buy_count
                                - sell_count
                        required:
                          - matched
                          - total_trades
                          - buy_count
                          - sell_count
                          - other_count
                          - total_value
                          - avg_value
                          - latest_trade_date
                          - earliest_trade_date
                          - source
                          - coverage_note
                          - ticker
                          - source_ticker
                          - issuer_name
                          - buy_sell_ratio
                          - unique_politicians
                          - top_politicians
        '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.