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

> Public Capitol Trades disclosures for an unambiguous member surname, full display name or native member ID. Supports publication/transaction-date/reporting-delay sorts and complete-result value sorting for members with at most 100 indexed disclosures. The source limits history to three years. One-hour cursors bind identity, sort and window. Empty results are free; ambiguous identities and unavailable source data fail closed.

Returns public disclosures from the [Capitol Trades index](https://www.capitoltrades.com/trades) for `handle=Pelosi`, a full display name such as `Nancy Pelosi`, or a native member ID such as `P000197`. A surname must resolve to one indexed member and agree with returned disclosure surnames. Ambiguous surnames return 422; use the full display name or member ID. Unindexed members return an empty result. This directory reflects the source index, not a complete current Congress roster.

`sort` accepts `pub_date` (default), `tx_date`, `reporting_gap` and `value`; `order` is `asc` or `desc` (default). Dates and delay use native source ordering, corroborated across every fetched row. **Value sorting is supported only when the member's complete indexed history fits in 100 disclosures.** The adapter fetches that complete result, then sorts and slices it. Larger histories return an unbilled `422 UNSUPPORTED_PARAMETER`; a partial page is never presented as globally sorted.

Use `limit` 1–100 (default 20), `offset` 0–1,000,000, or a returned `next_cursor` alone. Cursors bind member, sort/order, size and offset for one hour and recheck the preceding trade. New or edited source records can require restarting. Use a full display name/member ID for a terminal offset without a previous surname-verified cursor: an empty source page cannot independently corroborate a surname.

The source says its available history is restricted to the past **three years**. `total` means the current indexed matching count, not lifetime filings or complete government coverage. Rows preserve source IDs, member name/party/state/chamber, issuer/ticker/sector, publication and trade dates, transaction type, owner, reporting gap, estimated value and nullable price. Values are estimates. Birth dates and gender are omitted.

Requests reuse the existing Firecrawl basic transport: one anonymous public directory read and at most two disclosure pages, a shared 55-second deadline, a 4 MiB decoded HTML limit per page and 20 source reads/minute. Page data is parsed without executing scripts. No new account, key or purchase is required.

A fresh nonempty response costs **1 credit**. Empty results, errors, cached responses and successful idempotent replays cost zero. Use `X-Max-Credits: 1`. Existing approved provider free allowance only.


## OpenAPI

````yaml GET /us_congress_trades/politician/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/politician/trades:
    get:
      tags:
        - Us Congress Trades
      summary: Us Congress Trades Politician Trades
      description: >-
        Public Capitol Trades disclosures for an unambiguous member surname,
        full display name or native member ID. Supports
        publication/transaction-date/reporting-delay sorts and complete-result
        value sorting for members with at most 100 indexed disclosures. The
        source limits history to three years. One-hour cursors bind identity,
        sort and window. Empty results are free; ambiguous identities and
        unavailable source data fail closed.
      operationId: get_us_congress_trades_politician_trades
      parameters:
        - name: handle
          in: query
          required: false
          example: Pelosi
          schema:
            type: string
          description: >-
            Unambiguous member surname (corroborated against disclosures), full
            source display name or native member ID. Alternatively supply a
            returned cursor.
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - pub_date
              - tx_date
              - value
              - reporting_gap
          description: >-
            Default pub_date. Value sort requires the complete indexed member
            history to fit in 100 disclosures; larger histories return 422
            UNSUPPORTED_PARAMETER without charge.
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
          description: asc or desc (default desc).
        - 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. Use full display
            name/member ID to verify a terminal window without prior surname
            evidence.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            One-hour cursor, usable alone. Binds member, sort/order and size;
            checks the previous 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 disclosures for an unambiguous member surname,
            full display name or native member ID. Supports
            publication/transaction-date/reporting-delay sorts and
            complete-result value sorting for members with at most 100 indexed
            disclosures. The source limits history to three years. One-hour
            cursors bind identity, sort and window. Empty results are free;
            ambiguous identities and unavailable source data fail closed.
          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
                          handle:
                            type: string
                          politician:
                            type:
                              - object
                              - 'null'
                            properties:
                              id:
                                type: string
                              name:
                                type: string
                            required:
                              - id
                              - name
                          sort:
                            type: string
                            enum:
                              - pub_date
                              - tx_date
                              - value
                              - reporting_gap
                          order:
                            type: string
                            enum:
                              - asc
                              - desc
                          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
                          - handle
                          - politician
                          - sort
                          - order
                          - 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.