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

# Congressional Trades by Ticker

> Public Capitol Trades indexed disclosures for an exact ticker. Bare symbols default to :US. Supports party/chamber/type and publication-date filters, 1–100-row windows, offset up to 1000000 and a one-hour bound cursor. Totals describe the current index, not lifetime coverage. Incomplete or ambiguous issuer lookups fail closed; unindexed tickers and empty pages are free.

Returns public STOCK Act disclosures from the [Capitol Trades index](https://www.capitoltrades.com/trades) for an exactly resolved issuer. Supply `keyword=AAPL` or `keyword=AAPL:US`; bare tickers default to `:US`. The anonymous public issuer directory must return a complete, unambiguous exact match. An unindexed ticker returns an empty result with `issuer: null`; an incomplete or ambiguous lookup fails without charging.

Optional filters are `party` (democrat/republican), `chamber` (house/senate), `tx_type` (buy/sell/exchange), and inclusive `start_date`/`end_date` in YYYY-MM-DD format. Dates filter **publication dates**, not transaction dates. Results use descending publication order. Omitted start/end bounds use 1900-01-01/the request's UTC date when a date filter is present.

Use `limit` (1–100; default 20) and `offset` (0–1,000,000), or a returned `next_cursor` alone. Cursors bind the resolved issuer, all filters, window size and offset for one hour and recheck the preceding trade ID. Source edits or added filings can require restarting. Totals describe the current indexed matching disclosures, not lifetime trading activity or complete government coverage.

Rows preserve native IDs, politician name/party/state/chamber, issuer/ticker/sector, publication timestamp, trade date, transaction type, owner label, reporting gap, estimated value and nullable price. **Disclosed values are source estimates, not exact transaction amounts.** Birth dates and gender are omitted. Every row must agree with the requested filters and rendered trade links.

The adapter makes one anonymous issuer lookup and at most two native 100-row page reads through the existing Firecrawl basic transport. It has a shared 55-second timeout, a 1 MiB issuer-response limit, a 4 MiB decoded HTML limit per page and 20 source reads/minute. Original page scripts are parsed as data without execution. No new account or key is required.

A fresh nonempty response costs **1 credit**. Empty results, errors, cache hits and successful idempotent replays cost zero. Use `X-Max-Credits: 1`. Provider requests stay within the existing approved Firecrawl free allowance; no paid plan or replenishment is enabled.


## OpenAPI

````yaml GET /us_congress_trades/ticker/trades
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/trades:
    get:
      tags:
        - Us Congress Trades
      summary: Us Congress Trades Ticker Trades
      description: >-
        Public Capitol Trades indexed disclosures for an exact ticker. Bare
        symbols default to :US. Supports party/chamber/type and publication-date
        filters, 1–100-row windows, offset up to 1000000 and a one-hour bound
        cursor. Totals describe the current index, not lifetime coverage.
        Incomplete or ambiguous issuer lookups fail closed; unindexed tickers
        and empty pages are free.
      operationId: get_us_congress_trades_ticker_trades
      parameters:
        - name: keyword
          in: query
          required: false
          example: AAPL
          schema:
            type: string
          description: >-
            Bare ticker or source ticker with two-letter market suffix; bare
            symbols default to :US. Alternatively supply a returned cursor.
        - name: chamber
          in: query
          required: false
          schema:
            type: string
            enum:
              - senate
              - house
        - name: party
          in: query
          required: false
          schema:
            type: string
            enum:
              - democrat
              - republican
        - name: tx_type
          in: query
          required: false
          example: buy
          schema:
            type: string
            enum:
              - buy
              - sell
              - exchange
        - name: start_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Inclusive disclosure publication date, YYYY-MM-DD; this is not the
            transaction date.
        - name: end_date
          in: query
          required: false
          schema:
            type: string
            format: date
          description: >-
            Inclusive disclosure publication date, YYYY-MM-DD; this is not the
            transaction date.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
          description: 1–100 rows, default 20.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 1000000
          description: Rows to skip, 0–1000000. Prefer next_cursor.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            One-hour next_cursor, usable alone. Binds resolved ticker, filters
            and size and verifies the preceding disclosure. Source changes
            require restarting.
        - 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: >-
            Public Capitol Trades indexed disclosures for an exact ticker. Bare
            symbols default to :US. Supports party/chamber/type and
            publication-date filters, 1–100-row windows, offset up to 1000000
            and a one-hour bound cursor. Totals describe the current index, not
            lifetime coverage. Incomplete or ambiguous issuer lookups fail
            closed; unindexed tickers and empty pages are free.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            items:
                              type: object
                              properties:
                                id:
                                  type: string
                                url:
                                  type: string
                                issuer:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    name:
                                      type: string
                                    ticker:
                                      type:
                                        - string
                                        - 'null'
                                    sector:
                                      type:
                                        - string
                                        - 'null'
                                  required:
                                    - id
                                    - name
                                    - ticker
                                    - sector
                                politician:
                                  type: object
                                  properties:
                                    id:
                                      type: string
                                    first_name:
                                      type: string
                                    last_name:
                                      type: string
                                    display_name:
                                      type: string
                                    party:
                                      type: string
                                    state:
                                      type: string
                                    chamber:
                                      type: string
                                  required:
                                    - id
                                    - first_name
                                    - last_name
                                    - display_name
                                    - party
                                    - state
                                    - chamber
                                pub_date:
                                  type: string
                                tx_date:
                                  type: string
                                tx_type:
                                  type: string
                                owner:
                                  type:
                                    - string
                                    - 'null'
                                reporting_gap_days:
                                  type: integer
                                  minimum: 0
                                value_estimate_usd:
                                  type: integer
                                  minimum: 0
                                price_usd:
                                  type:
                                    - number
                                    - 'null'
                              required:
                                - id
                                - url
                                - issuer
                                - politician
                                - pub_date
                                - tx_date
                                - tx_type
                                - owner
                                - reporting_gap_days
                                - value_estimate_usd
                                - price_usd
                          returned_count:
                            type: integer
                            minimum: 0
                          total:
                            type: integer
                            minimum: 0
                          keyword:
                            type: string
                          issuer:
                            type:
                              - object
                              - 'null'
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                              ticker:
                                type: string
                            required:
                              - id
                              - name
                              - ticker
                          filters:
                            type: object
                            properties:
                              party:
                                type: string
                              chamber:
                                type: string
                              tx_type:
                                type: string
                              start_date:
                                type: string
                              end_date:
                                type: string
                            additionalProperties: false
                          limit:
                            type: integer
                            minimum: 1
                            maximum: 100
                          offset:
                            type: integer
                            minimum: 0
                          has_more:
                            type: boolean
                          next_cursor:
                            type:
                              - string
                              - 'null'
                          source:
                            type: string
                          coverage_note:
                            type: string
                        required:
                          - items
                          - returned_count
                          - total
                          - keyword
                          - issuer
                          - filters
                          - limit
                          - offset
                          - has_more
                          - next_cursor
                          - 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.