> ## Documentation Index
> Fetch the complete documentation index at: https://docs.simmer.markets/llms.txt
> Use this file to discover all available pages before exploring further.

# List Markets

> List markets available for SDK trading.

By default, excludes tracking markets (no AI counterparty for simmer trading).
Set include_analytics_only=true to include them (for real trading only).

Parameters:
- status: Filter by status ('active', 'resolved', etc.). Omit to get all statuses when using ids.
- venue: Filter by venue ('polymarket', 'sim'). Alias for import_source.
        Deprecated: 'sandbox'/'simmer' are accepted but deprecated, use 'sim' instead.
- import_source: Same as venue (kept for backwards compatibility).
- q: Text search for market questions (min 2 chars, case-insensitive)
- ids: Comma-separated market IDs to fetch (max 50). When provided, status filter is optional.
- tags: Comma-separated tags to filter by (e.g., 'weather' or 'weather,crypto'). Returns markets with ALL specified tags.
- sort: 'volume' (by 24h volume), 'recent'/'created' (by created_at), or None (default by 24h volume)
- include: Comma-separated optional response fields. `resolution_criteria` is
           returned by default for active-market source verification; the
           include value remains accepted for older SDK callers.
- tradeable_only: Defaults true. Set false to include active DB rows even
           when Redis/CLOB liveness checks mark the orderbook unavailable.

Each market row includes `seconds_to_resolution` (float seconds until
`resolves_at`, server-computed at response time; null when the market has
no resolution timestamp, negative once it has passed). Prefer it over
computing expiry from `resolves_at` locally — it is immune to host clock
skew and matches replay semantics.

Unknown params will trigger a warning in the response (helps debug typos).
Requires API key in Authorization header.

<Tip>Need `time_to_resolution`, slippage, or flip-flop detection? Use the [context endpoint](/api-reference/context) — those fields are not on `/markets`.</Tip>

**Discovery cap:** `/api/sdk/markets` returns at most 1,000 matching markets for a discovery window, then applies `limit`/`offset` within that capped window (max 500 results per request, default 50). The response `total` is the window size, not the full catalog count. When your query hits the ceiling, the response includes `"truncated": true` and `"capped_at_limit": true`; use `tags`, `q`, `venue`, `sort`, or `max_hours_to_resolution` to narrow the search. Filters are applied before the cap, so `tags=world-cup&sort=volume` means "top markets inside the World Cup slice," not "filter this page." Market imports are not subject to this discovery-read cap.

## Response fields

Each entry in `markets[]` has the same shape as [`GET /api/sdk/markets/{market_id}`](/api-reference/get-market). See that page for the full field reference, including resolution fields (`status`, `resolved_at`, `outcome`).


## OpenAPI

````yaml /openapi.json get /api/sdk/markets
openapi: 3.1.0
info:
  title: Simmer API
  description: Agent-native trading infrastructure for prediction markets.
  version: 1.0.0
servers:
  - url: https://api.simmer.markets
security: []
paths:
  /api/sdk/markets:
    get:
      summary: List Markets
      description: >-
        List markets available for SDK trading.


        By default, excludes tracking markets (no AI counterparty for simmer
        trading).

        Set include_analytics_only=true to include them (for real trading only).


        Parameters:

        - status: Filter by status ('active', 'resolved', etc.). Omit to get all
        statuses when using ids.

        - venue: Filter by venue ('polymarket', 'sim'). Alias for import_source.
                Deprecated: 'sandbox'/'simmer' are accepted but deprecated, use 'sim' instead.
        - import_source: Same as venue (kept for backwards compatibility).

        - q: Text search for market questions (min 2 chars, case-insensitive)

        - ids: Comma-separated market IDs to fetch (max 50). When provided,
        status filter is optional.

        - tags: Comma-separated tags to filter by (e.g., 'weather' or
        'weather,crypto'). Returns markets with ALL specified tags.

        - sort: 'volume' (by 24h volume), 'recent'/'created' (by created_at), or
        None (default by 24h volume)

        - include: Comma-separated optional response fields.
        `resolution_criteria` is
                   returned by default for active-market source verification; the
                   include value remains accepted for older SDK callers.
        - tradeable_only: Defaults true. Set false to include active DB rows
        even
                   when Redis/CLOB liveness checks mark the orderbook unavailable.

        Each market row includes `seconds_to_resolution` (float seconds until

        `resolves_at`, server-computed at response time; null when the market
        has

        no resolution timestamp, negative once it has passed). Prefer it over

        computing expiry from `resolves_at` locally — it is immune to host clock

        skew and matches replay semantics.


        Unknown params will trigger a warning in the response (helps debug
        typos).

        Requires API key in Authorization header.
      operationId: api_sdk_list_markets_api_sdk_markets_get
      parameters:
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            default: active
            title: Status
        - name: import_source
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Import Source
        - name: venue
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Venue
        - name: q
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Q
        - name: ids
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Ids
        - name: tags
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Tags
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 50
            title: Limit
        - name: offset
          in: query
          required: false
          schema:
            type: integer
            default: 0
            title: Offset
        - name: include_analytics_only
          in: query
          required: false
          schema:
            type: boolean
            default: false
            title: Include Analytics Only
        - name: sort
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Sort
        - name: max_hours_to_resolution
          in: query
          required: false
          schema:
            anyOf:
              - type: integer
              - type: 'null'
            title: Max Hours To Resolution
        - name: include
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            title: Include
        - name: tradeable_only
          in: query
          required: false
          schema:
            type: boolean
            default: true
            title: Tradeable Only
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError

````