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

# Congress disclosure counts by sector

> Disclosed-trade counts by the eleven native issuer sectors, plus an explicit unclassified residual. Counts come from complete native filtered totals, not sample proportions. The snapshot covers the public Capitol Trades three-year index, refreshes daily and expires after 48 hours. A final unfiltered anchor is rechecked before publication; independently collected source totals are not an atomic source snapshot. One credit for a nonempty uncached aggregate; a verified all-zero index, errors, cache hits and idempotent replay are free. No query filters are accepted. Cache bypass reads the latest complete snapshot without triggering source collection.

Returns **eleven named sectors and an unclassified remainder** from the public Capitol Trades index. Each row has `sector`, `trade_count`, `share` and `count_kind`. Named sectors use native filtered totals; `unclassified` is the exact residual after subtracting their disjoint totals from `total_disclosures`. It is not the source's `other` filter and is not estimated from sampled rows.

Counts cover the source's roughly **three-year public index**, not lifetime trades or all government filings. `classified_disclosures` plus `unclassified_disclosures` equals `total_disclosures`, and all twelve row counts reconcile to that total.

A background worker collects one source page per step and validates all twelve totals. It rechecks the initial unfiltered total and first-page identities before publishing; incomplete or inconsistent refreshes retain the previous complete snapshot. The source does not offer an atomic historical snapshot. `retrieved_at` records collection start, `collected_at` records completion, and `snapshot_id` identifies the published result. None is a fabricated source last-updated time.

Snapshots refresh daily and expire after **48 hours**. Missing or expired snapshots return uncharged 503. A response-cache hit cannot extend snapshot expiry. A successful idempotent replay preserves its original dated payload under the normal 24-hour replay contract; it is historical request evidence, not a fresh snapshot. `Cache-Control: no-cache` bypasses the API response cache but does not trigger collection.

An uncached nonempty aggregate costs **1 credit**. A verified index with zero total disclosures is free, as are errors, cache hits and idempotent replays. Use `X-Max-Credits: 1`. No query parameters, per-sector filters, custom date windows or pagination are accepted.

Background collection currently uses a non-resetting allowance of 28 reads from existing Firecrawl trial capacity. Exhausting it prevents future refreshes; this is not evidence of sustained provider funding.


## OpenAPI

````yaml GET /us_congress_trades/stats/sectors
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/stats/sectors:
    get:
      tags:
        - Us Congress Trades
      summary: Us Congress Trades Stats Sectors
      description: >-
        Disclosed-trade counts by the eleven native issuer sectors, plus an
        explicit unclassified residual. Counts come from complete native
        filtered totals, not sample proportions. The snapshot covers the public
        Capitol Trades three-year index, refreshes daily and expires after 48
        hours. A final unfiltered anchor is rechecked before publication;
        independently collected source totals are not an atomic source snapshot.
        One credit for a nonempty uncached aggregate; a verified all-zero index,
        errors, cache hits and idempotent replay are free. No query filters are
        accepted. Cache bypass reads the latest complete snapshot without
        triggering source collection.
      operationId: get_us_congress_trades_stats_sectors
      parameters:
        - 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: >-
            Disclosed-trade counts by the eleven native issuer sectors, plus an
            explicit unclassified residual. Counts come from complete native
            filtered totals, not sample proportions. The snapshot covers the
            public Capitol Trades three-year index, refreshes daily and expires
            after 48 hours. A final unfiltered anchor is rechecked before
            publication; independently collected source totals are not an atomic
            source snapshot. One credit for a nonempty uncached aggregate; a
            verified all-zero index, errors, cache hits and idempotent replay
            are free. No query filters are accepted. Cache bypass reads the
            latest complete snapshot without triggering source collection.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          items:
                            type: array
                            minItems: 12
                            maxItems: 12
                            items:
                              type: object
                              properties:
                                sector:
                                  type: string
                                trade_count:
                                  type: integer
                                  minimum: 0
                                share:
                                  type: number
                                  minimum: 0
                                  maximum: 1
                                count_kind:
                                  type: string
                                  enum:
                                    - native_total
                                    - residual
                              required:
                                - sector
                                - trade_count
                                - share
                                - count_kind
                              additionalProperties: false
                          returned_count:
                            const: 12
                          total_disclosures:
                            type: integer
                            minimum: 0
                          classified_disclosures:
                            type: integer
                            minimum: 0
                          unclassified_disclosures:
                            type: integer
                            minimum: 0
                          source:
                            type: string
                            format: uri
                          retrieved_at:
                            type: string
                            format: date-time
                          coverage_note:
                            type: string
                          snapshot_id:
                            type: string
                          collected_at:
                            type: string
                            format: date-time
                          expires_at:
                            type: string
                            format: date-time
                          source_reads:
                            const: 13
                        required:
                          - items
                          - returned_count
                          - total_disclosures
                          - classified_disclosures
                          - unclassified_disclosures
                          - source
                          - retrieved_at
                          - coverage_note
                          - snapshot_id
                          - collected_at
                          - expires_at
                          - source_reads
                        additionalProperties: false
                    required:
                      - data
        '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.