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

# List venue events

> Returns paginated venue events with optional filters for venue, status, category, and search. DEPRECATION: the per-item `description` field is deprecated and will be removed from list responses — fetch the full event (including `description`) via GET /venue-events/:id. The embedded `venueMarkets` on each item are a top-N preview only; for the full market list use GET /venue-markets?venueEventId=.



## OpenAPI

````yaml /openapi/openapi.json get /venue-events
openapi: 3.0.2
info:
  title: AGG API
  version: 1.0.0
  description: >-
    Prediction market aggregator REST API — authentication, users, venue events,
    venue markets, orderbooks, charts, and execution workflows.
servers:
  - url: https://api.agg.market
    description: Production
  - url: https://api.staging.agg.market
    description: Staging
security: []
paths:
  /venue-events:
    get:
      tags:
        - Discovery
      summary: List venue events
      description: >-
        Returns paginated venue events with optional filters for venue, status,
        category, and search. DEPRECATION: the per-item `description` field is
        deprecated and will be removed from list responses — fetch the full
        event (including `description`) via GET /venue-events/:id. The embedded
        `venueMarkets` on each item are a top-N preview only; for the full
        market list use GET /venue-markets?venueEventId=.
      operationId: listVenueEvents
      parameters:
        - name: venues
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  enum:
                    - kalshi
                    - polymarket
                    - limitless
                    - opinion
                    - predict
                    - probable
                    - myriad
                    - hyperliquid
              - type: string
                enum:
                  - kalshi
                  - polymarket
                  - limitless
                  - opinion
                  - predict
                  - probable
                  - myriad
                  - hyperliquid
        - name: search
          in: query
          required: false
          schema:
            type: string
        - name: matchStatus
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  enum:
                    - pending
                    - unmatched
                    - review
                    - matched
                    - verified
                    - rejected
              - type: string
                enum:
                  - pending
                  - unmatched
                  - review
                  - matched
                  - verified
                  - rejected
        - name: categoryIds
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: string
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  enum:
                    - open
                    - closed
                    - resolved
                    - unopened
                    - paused
              - type: string
                enum:
                  - open
                  - closed
                  - resolved
                  - unopened
                  - paused
        - name: sortDir
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
        - name: sortBy
          in: query
          required: false
          schema:
            type: string
            enum:
              - volume
              - volume24hr
              - createdAt
              - endDate
              - arbReturn
        - name: limit
          in: query
          required: false
          schema:
            minimum: 1
            maximum: 100
            type: number
        - name: cursor
          in: query
          required: false
          schema:
            type: string
        - name: grouped
          in: query
          required: false
          schema:
            type: string
            enum:
              - 'true'
              - 'false'
        - name: aggKey
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
              - type: string
        - name: recurrence
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  type: string
                  enum:
                    - PT5M
                    - PT10M
                    - PT15M
                    - PT1H
                    - P1D
                    - P1W
                    - P1M
                    - P1Y
                    - 'null'
              - type: string
                enum:
                  - PT5M
                  - PT10M
                  - PT15M
                  - PT1H
                  - P1D
                  - P1W
                  - P1M
                  - P1Y
                  - 'null'
      responses:
        '200':
          description: '200'
          content:
            application/json:
              schema:
                type: object
                required:
                  - data
                  - nextCursor
                  - hasMore
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      required:
                        - id
                        - externalIdentifier
                        - title
                        - image
                        - venue
                        - categories
                      properties:
                        id:
                          description: >-
                            Event id. List responses return one row per matched
                            cluster, and for a matched event this id is the
                            cluster anchor — the handle to use for cross-venue
                            lookups. Re-resolve it from discovery rather than
                            storing it as a permanent key: clusters can merge,
                            after which the id remains a valid event but is no
                            longer the cluster head. See the Matched Clusters
                            guide.
                          type: string
                        externalIdentifier:
                          type: string
                        title:
                          type: string
                        description:
                          type: string
                          nullable: true
                        image:
                          type: string
                          nullable: true
                        venue:
                          type: string
                          enum:
                            - kalshi
                            - polymarket
                            - limitless
                            - opinion
                            - predict
                            - probable
                            - myriad
                            - hyperliquid
                        volume:
                          minimum: 0
                          type: number
                          nullable: true
                        status:
                          type: string
                          enum:
                            - open
                            - closed
                            - resolved
                            - unopened
                            - paused
                        startDate:
                          type: string
                          nullable: true
                        endDate:
                          type: string
                          nullable: true
                        creationDate:
                          type: string
                          nullable: true
                        gameStartTime:
                          type: string
                          nullable: true
                        categories:
                          type: array
                          items:
                            type: object
                            required:
                              - id
                              - category
                            properties:
                              id:
                                type: string
                              category:
                                type: object
                                required:
                                  - id
                                  - name
                                  - displayName
                                  - parentId
                                  - eventCount
                                  - volume24hr
                                  - volume
                                properties:
                                  id:
                                    type: string
                                  name:
                                    type: string
                                  displayName:
                                    type: string
                                    nullable: true
                                  parentId:
                                    type: string
                                    nullable: true
                                  eventCount:
                                    type: number
                                  volume24hr:
                                    type: number
                                  volume:
                                    type: number
                        slug:
                          type: string
                          nullable: true
                        subtitle:
                          type: string
                          nullable: true
                        venues:
                          description: >-
                            Venues this row's matched cluster spans — use it for
                            venue badges. On a cluster anchor this is the
                            cluster-wide set; a non-anchor member usually
                            reports the same set, but narrows to its own venue
                            when none of its markets have cross-venue
                            counterparts.
                          type: array
                          items:
                            type: string
                            enum:
                              - kalshi
                              - polymarket
                              - limitless
                              - opinion
                              - predict
                              - probable
                              - myriad
                              - hyperliquid
                        marketCount:
                          minimum: 0
                          description: >-
                            Number of markets on this event. Use this rather
                            than the length of an embedded venueMarkets array,
                            which is a preview on list responses.
                          type: integer
                        venueCount:
                          minimum: 0
                          description: >-
                            Length of `venues` — the size of the matched
                            cluster.
                          type: integer
                        groupMarketCount:
                          minimum: 0
                          type: integer
                        updatedAt:
                          type: string
                          nullable: true
                        venueMarkets:
                          description: >-
                            Embedded markets. On list responses this is a
                            preview of up to three markets chosen to represent
                            the event on a card — not the complete set, and not
                            necessarily the largest; use marketCount for totals.
                            On the by-id response it is uncapped. Deprecated on
                            both — fetch markets from GET
                            /venue-markets?venueEventId=.
                          type: array
                          items:
                            type: object
                            required:
                              - id
                              - venue
                              - externalIdentifier
                              - question
                              - venueMarketOutcomes
                            properties:
                              id:
                                type: string
                              venue:
                                type: string
                                enum:
                                  - kalshi
                                  - polymarket
                                  - limitless
                                  - opinion
                                  - predict
                                  - probable
                                  - myriad
                                  - hyperliquid
                              marketId:
                                type: string
                                nullable: true
                              externalIdentifier:
                                type: string
                              venueEventId:
                                type: string
                                nullable: true
                              question:
                                type: string
                              description:
                                type: string
                                nullable: true
                              rulesPrimary:
                                type: string
                                nullable: true
                              rulesSecondary:
                                type: string
                                nullable: true
                              conditionId:
                                type: string
                                nullable: true
                              volume:
                                minimum: 0
                                type: number
                                nullable: true
                              image:
                                type: string
                                nullable: true
                              venueMarketOutcomes:
                                type: array
                                items:
                                  type: object
                                  required:
                                    - id
                                    - venueMarketId
                                    - label
                                  properties:
                                    id:
                                      type: string
                                    venueMarketId:
                                      type: string
                                    externalIdentifier:
                                      type: string
                                      nullable: true
                                    label:
                                      type: string
                                    title:
                                      type: string
                                      nullable: true
                                    price:
                                      minimum: 0
                                      maximum: 1
                                      deprecated: true
                                      description: >-
                                        No longer returned. Fetch live prices
                                        from GET /midpoints (pass this outcome's
                                        parent venueMarketId in `ids` and match
                                        on `outcomes[].venueMarketOutcomeId`),
                                        or subscribe to the WebSocket midpoint
                                        stream.
                                      type: number
                                    winner:
                                      type: boolean
                                      nullable: true
                                    matchedVenueMarketOutcomes:
                                      type: array
                                      items:
                                        type: object
                                        required:
                                          - venueMarketId
                                          - venueMarketOutcomeId
                                        properties:
                                          venueMarketId:
                                            type: string
                                          venueMarketOutcomeId:
                                            type: string
                                    matchDecision:
                                      type: object
                                      required:
                                        - decision
                                        - reasonPresets
                                        - reasonText
                                        - decidedBy
                                        - decidedAt
                                      properties:
                                        decision:
                                          type: string
                                          enum:
                                            - verified
                                            - rejected
                                        reasonPresets:
                                          type: array
                                          items:
                                            type: string
                                        reasonText:
                                          type: string
                                          nullable: true
                                        decidedBy:
                                          type: string
                                        decidedAt:
                                          anyOf:
                                            - type: string
                                            - format: date-time
                                              type: string
                                      nullable: true
                              status:
                                type: string
                                enum:
                                  - open
                                  - closed
                                  - resolved
                                  - unopened
                                  - paused
                              startDate:
                                type: string
                                nullable: true
                              endDate:
                                type: string
                                nullable: true
                              creationDate:
                                type: string
                                nullable: true
                              createdAt:
                                type: string
                                nullable: true
                              resolutionDate:
                                type: string
                                nullable: true
                              negRisk:
                                type: boolean
                              venues:
                                type: array
                                items:
                                  type: string
                                  enum:
                                    - kalshi
                                    - polymarket
                                    - limitless
                                    - opinion
                                    - predict
                                    - probable
                                    - myriad
                                    - hyperliquid
                              venueCount:
                                minimum: 0
                                type: integer
                              matchStatus:
                                type: string
                                enum:
                                  - pending
                                  - unmatched
                                  - review
                                  - matched
                                  - verified
                                  - rejected
                                nullable: true
                              arbReturn:
                                type: number
                                nullable: true
                              aggKey:
                                description: >-
                                  Deterministic canonical key computed from this
                                  venue's own data; null when not
                                  canonicalizable. This is a fetch filter, not a
                                  cross-venue join key — it is guaranteed
                                  identical across venues only for sports
                                  head-to-head and crypto up/down markets, and
                                  two members of the same matched cluster can
                                  carry different keys. Use the event id and
                                  matchedVenueMarkets for identity.
                                type: string
                                nullable: true
                              sportsMarketType:
                                type: string
                                nullable: true
                              sectionRank:
                                type: integer
                                nullable: true
                              period:
                                type: string
                                nullable: true
                              marketCategory:
                                type: string
                                nullable: true
                              marketGroup:
                                type: string
                                nullable: true
                              marketSubtype:
                                type: string
                                nullable: true
                              lineValue:
                                type: number
                                nullable: true
                              matchedVenueMarkets:
                                description: >-
                                  The same market on other venues, as linked by
                                  AGG's matching pipeline. This is the
                                  cross-venue linkage — it hangs off each
                                  market, not off the event, and is complete
                                  regardless of which cluster member you
                                  queried.
                                type: array
                                items:
                                  type: object
                                  required:
                                    - id
                                    - venue
                                    - externalIdentifier
                                    - question
                                  properties:
                                    id:
                                      type: string
                                    venue:
                                      type: string
                                      enum:
                                        - kalshi
                                        - polymarket
                                        - limitless
                                        - opinion
                                        - predict
                                        - probable
                                        - myriad
                                        - hyperliquid
                                    externalIdentifier:
                                      type: string
                                    question:
                                      type: string
                                    description:
                                      type: string
                                      nullable: true
                                    rulesPrimary:
                                      type: string
                                      nullable: true
                                    rulesSecondary:
                                      type: string
                                      nullable: true
                                    volume:
                                      minimum: 0
                                      type: number
                                      nullable: true
                                    status:
                                      type: string
                                      enum:
                                        - open
                                        - closed
                                        - resolved
                                        - unopened
                                        - paused
                                    conditionId:
                                      type: string
                                      nullable: true
                                    matchStatus:
                                      type: string
                                      enum:
                                        - pending
                                        - unmatched
                                        - review
                                        - matched
                                        - verified
                                        - rejected
                                      nullable: true
                                    arbReturn:
                                      type: number
                                      nullable: true
                                    shortTitle:
                                      type: string
                                      nullable: true
                                    image:
                                      type: string
                                      nullable: true
                                    venueEvent:
                                      type: object
                                      required:
                                        - id
                                        - externalIdentifier
                                      properties:
                                        id:
                                          type: string
                                        externalIdentifier:
                                          type: string
                                        slug:
                                          type: string
                                          nullable: true
                                        title:
                                          type: string
                                          nullable: true
                                        series:
                                          type: object
                                          required:
                                            - id
                                            - venue
                                            - externalIdentifier
                                          properties:
                                            id:
                                              type: string
                                            name:
                                              type: string
                                              nullable: true
                                            venue:
                                              type: string
                                            externalIdentifier:
                                              type: string
                                          nullable: true
                                      nullable: true
                                    venueMarketOutcomes:
                                      type: array
                                      items:
                                        type: object
                                        required:
                                          - id
                                          - venueMarketId
                                          - label
                                        properties:
                                          id:
                                            type: string
                                          venueMarketId:
                                            type: string
                                          label:
                                            type: string
                                          title:
                                            type: string
                                            nullable: true
                                          price:
                                            deprecated: true
                                            description: >-
                                              No longer returned. Fetch live prices
                                              from GET /midpoints — sibling outcomes
                                              are covered by the `matched[]` entries
                                              of the parent market's midpoint item.
                                            type: number
                                          winner:
                                            type: boolean
                                            nullable: true
                        matchStatus:
                          type: string
                          enum:
                            - pending
                            - unmatched
                            - review
                            - matched
                            - verified
                            - rejected
                          nullable: true
                        arbReturn:
                          type: number
                          nullable: true
                        series:
                          type: object
                          required:
                            - externalIdentifier
                          properties:
                            externalIdentifier:
                              type: string
                          nullable: true
                        recurrence:
                          type: string
                          nullable: true
                        aggKey:
                          description: >-
                            Deterministic canonical key computed from this
                            venue's own data; null when not canonicalizable.
                            This is a fetch filter, not a cross-venue join key —
                            it is guaranteed identical across venues only for
                            sports head-to-head and crypto up/down markets, and
                            two members of the same matched cluster can carry
                            different keys. Use the event id and
                            matchedVenueMarkets for identity.
                          type: string
                          nullable: true
                        structureType:
                          type: string
                          enum:
                            - candidate
                            - sport
                            - axis
                            - dates
                          nullable: true
                        sport:
                          type: string
                          nullable: true
                        settlementDiff:
                          type: object
                          required:
                            - sharedSummary
                            - differences
                          properties:
                            sharedSummary:
                              type: string
                            differences:
                              type: array
                              items:
                                type: object
                                required:
                                  - type
                                  - title
                                  - perVenue
                                properties:
                                  type:
                                    type: string
                                  title:
                                    type: string
                                  perVenue:
                                    type: object
                                    additionalProperties:
                                      type: string
                                  summary:
                                    type: string
                          nullable: true
                  nextCursor:
                    type: string
                    nullable: true
                  hasMore:
                    type: boolean
        '400':
          description: '400'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
        '401':
          description: '401'
          content:
            application/json:
              schema:
                type: object
                required:
                  - message
                properties:
                  message:
                    type: string
      security:
        - appId: []
components:
  securitySchemes:
    appId:
      type: apiKey
      in: header
      name: x-app-id
      description: Your application ID. Required for all app-tier and user-tier routes.

````