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

# Polymarket topic research

> Expand a research topic into up to six parallel public Gamma searches, deduplicate events by ID, filter unrelated titles by informative-word overlap and rank by lexical topic/title similarity. Costs 5 credits for a successful nonempty result. Every search must succeed; failures and empty results are uncharged. This is a bounded snapshot, not an exhaustive index or trading service. Framing prefixes such as last 30 days are stripped, not interpreted as date filters.

Supply a natural-language `query`, for example `last 30 days bitcoin halving`. SocialQuery removes framing prefixes, searches the core subject and individual informative words in parallel (up to six unique searches), deduplicates by event ID, discards unrelated titles, and ranks the remainder by lexical topic/title similarity. Native public Gamma event fields, including nested markets, are retained.

A successful nonempty result costs **5 credits**, regardless of the number of source searches. Errors, empty results, cache hits and successful idempotent replays cost zero. Use `X-Max-Credits: 5` to cap the charge. The official public [Gamma API](https://docs.polymarket.com/api-reference/search/search-markets-events-and-profiles) supplies metadata; this operation does not execute trades or access an account.

`limit` defaults to 10 and accepts 1–50 **per source search**, so the combined result may exceed it. All source searches must finish within 25 seconds. A failed or malformed source page causes an uncharged error, never a partial-success snapshot. Source pages are capped at 2 MiB and the combined result at 3 MiB; reduce `limit` if a response is too large.

`total` counts returned events. `duplicates_removed` and `unrelated_removed` explain consolidation; `dropped` is zero because malformed event pages fail the request. `source_has_more` is true if any source search reports more rows. This composite is a bounded first-page snapshot and has no continuation cursor (`next_cursor` is null); it does not claim the complete event index.

Time phrases such as `last 30 days` are query framing **only**, not event-date filters. Prefixes `what are people saying about`, `tell me about`, and `research on/about` are also removed. Matching uses informative words and lexical similarity, not language-model analysis. Use `/v1/polymarket/search` for a single raw search.


## OpenAPI

````yaml GET /polymarket/research
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:
  /polymarket/research:
    get:
      tags:
        - Polymarket
      summary: Polymarket Research
      description: >-
        Expand a research topic into up to six parallel public Gamma searches,
        deduplicate events by ID, filter unrelated titles by informative-word
        overlap and rank by lexical topic/title similarity. Costs 5 credits for
        a successful nonempty result. Every search must succeed; failures and
        empty results are uncharged. This is a bounded snapshot, not an
        exhaustive index or trading service. Framing prefixes such as last 30
        days are stripped, not interpreted as date filters.
      operationId: get_polymarket_research
      parameters:
        - name: query
          in: query
          required: true
          example: trump 2028 election
          schema:
            type: string
            minLength: 1
            maxLength: 500
          description: >-
            Natural-language topic. Leading last/past N days/weeks/months/years
            and what are people saying about framing is stripped. This does not
            apply a date filter.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 50
            default: 10
          description: >-
            Maximum events requested per source search, not an overall result
            limit. Up to six source searches are combined.
        - 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: >-
            Expand a research topic into up to six parallel public Gamma
            searches, deduplicate events by ID, filter unrelated titles by
            informative-word overlap and rank by lexical topic/title similarity.
            Costs 5 credits for a successful nonempty result. Every search must
            succeed; failures and empty results are uncharged. This is a bounded
            snapshot, not an exhaustive index or trading service. Framing
            prefixes such as last 30 days are stripped, not interpreted as date
            filters.
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/SocialQueryResponse'
                  - type: object
                    properties:
                      data:
                        type: object
                        required:
                          - items
                          - total
                          - next_cursor
                          - dropped
                          - topic
                          - queries
                          - source_calls
                          - duplicates_removed
                          - unrelated_removed
                          - source_has_more
                          - source
                          - coverage_note
                        properties:
                          items:
                            type: array
                            maxItems: 300
                            items:
                              type: object
                              required:
                                - id
                                - title
                              properties:
                                id:
                                  type: string
                                title:
                                  type: string
                                slug:
                                  type: string
                                description:
                                  type: string
                                active:
                                  type: boolean
                                closed:
                                  type: boolean
                                markets:
                                  type: array
                                  items:
                                    type: object
                                    additionalProperties: true
                              additionalProperties: true
                          total:
                            type: integer
                            minimum: 0
                          next_cursor:
                            type: 'null'
                          dropped:
                            const: 0
                          topic:
                            type: string
                          queries:
                            type: array
                            minItems: 1
                            maxItems: 6
                            items:
                              type: string
                          source_calls:
                            type: integer
                            minimum: 1
                            maximum: 6
                          duplicates_removed:
                            type: integer
                            minimum: 0
                          unrelated_removed:
                            type: integer
                            minimum: 0
                          source_has_more:
                            type: boolean
                          source:
                            type: string
                          coverage_note:
                            type: string
                        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.