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

> Public Capitol Trades STOCK Act disclosures filed by members from one US state, ordered by publication time descending. The total describes the current source index, not lifetime filings. Supports 1–100-row pages, offset up to 1000000 and a one-hour state-bound cursor. Missing/changed source data fail closed; empty pages are free.

Returns public STOCK Act disclosures filed by members from the requested state, using the [Capitol Trades disclosure index](https://www.capitoltrades.com/trades). It reuses SocialQuery's existing Firecrawl basic transport; no new account or key is required.

Supply a two-letter US state code or `DC`, `limit` (1–100; default 20), and `offset` (0–1,000,000), or pass a returned `next_cursor` alone. Cursors bind state, limit and offset for one hour and verify the preceding trade ID. Source edits, added filings or changed page totals can require restarting. Results use the source's descending publication order, not trade-date order. No additional filters or alternate sorts are supported on this operation.

Each disclosure preserves source IDs, politician name/party/state/chamber, issuer/ticker/sector, publication timestamp, trade date, transaction type, owner label, reporting gap, estimated disclosed value and nullable transaction price. **Values are source estimates, not exact amounts.** Birth date, gender and unrelated source fields are omitted. The `total` is the current state's indexed disclosure count; it is not lifetime trading activity, a complete government record or a guarantee of immediate filing coverage.

The adapter corroborates the applied state filter, every row's state, totals, page order and rendered disclosure links. It reads at most two native 100-row pages per request, with a 55-second shared timeout, 4 MiB decoded HTML limit per page and 20 source reads/minute. Original bytes are decoded without executing page scripts. Confirmed terminal offsets return an empty list with the source total and no cursor.

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


## OpenAPI

````yaml GET /us_congress_trades/state/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/state/trades:
    get:
      tags:
        - Us Congress Trades
      summary: Us Congress Trades State Trades
      description: >-
        Public Capitol Trades STOCK Act disclosures filed by members from one US
        state, ordered by publication time descending. The total describes the
        current source index, not lifetime filings. Supports 1–100-row pages,
        offset up to 1000000 and a one-hour state-bound cursor. Missing/changed
        source data fail closed; empty pages are free.
      operationId: get_us_congress_trades_state_trades
      parameters:
        - name: state
          in: query
          required: false
          example: CA
          schema:
            type: string
          description: >-
            Two-letter US postal state code or DC, case-insensitive;
            alternatively supply a returned cursor.
        - 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: >-
            Opaque one-hour next_cursor; binds state and window size. Can be
            supplied alone. Rechecks 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 STOCK Act disclosures filed by members from
            one US state, ordered by publication time descending. The total
            describes the current source index, not lifetime filings. Supports
            1–100-row pages, offset up to 1000000 and a one-hour state-bound
            cursor. Missing/changed source data fail closed; 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
                          state:
                            type: string
                          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
                          - state
                          - 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.