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

# Fetch matched event clusters

> Returns connected clusters of semantically matched events across venues. Use this endpoint to browse or anchor event-level matches while preserving each venue's child markets.




## OpenAPI

````yaml /api-reference/openapi-hosted.json get /v0/matched-event-clusters
openapi: 3.0.0
info:
  title: PMXT Hosted Router API
  description: Hosted-only endpoints for cross-venue search, matching, arbitrage, and SQL.
  version: 49fbcd4
servers:
  - url: https://api.pmxt.dev
    description: Production
security:
  - bearerAuth: []
tags:
  - name: Trading (Hosted)
    description: >-
      Hosted trading endpoints. Build / submit / cancel orders via
      `trade.pmxt.dev/v0/*`. Hosted-mode is the default when `pmxt_api_key` is
      set.
  - name: Orders & Positions (Hosted)
    description: >-
      Hosted account reads. Open orders, fills, balances, and positions via
      `trade.pmxt.dev/v0/*`. Requires `pmxt_api_key` + `wallet_address`.
  - name: MatchedMarkets
    description: Cross-venue matched market and event clusters.
  - name: SQL
    description: Direct read-only SQL access to the catalog (Enterprise).
paths:
  /v0/matched-event-clusters:
    get:
      tags:
        - MatchedMarkets
      summary: Fetch matched event clusters
      description: >
        Returns connected clusters of semantically matched events across venues.
        Use this endpoint to browse or anchor event-level matches while
        preserving each venue's child markets.
      operationId: getV0Matched-event-clusters
      parameters:
        - in: query
          name: eventId
          schema:
            type: string
          description: Anchor the response to a specific event ID.
        - in: query
          name: slug
          schema:
            type: string
          description: Anchor the response to a specific event slug.
        - in: query
          name: url
          schema:
            type: string
          description: Anchor the response to a specific event URL.
        - in: query
          name: query
          schema:
            type: string
          description: Text search across cluster titles.
          example: Satoshi
        - in: query
          name: category
          schema:
            type: string
          description: Filter both sides of matched edges by event category.
          example: Crypto
        - in: query
          name: relations
          schema:
            type: string
            default: identity
          description: >
            Comma-separated relation filter. Valid values: identity (same
            resolution), subset (A yes implies B yes), superset (B yes implies A
            yes), overlap (some shared scenarios), and disjoint (mutually
            exclusive). Defaults to identity. For subset and superset, direction
            follows the pairwise edge direction returned in rawMatches when
            includeRawMatches=true.
          example: identity
        - in: query
          name: relation
          schema:
            type: string
            enum:
              - identity
              - subset
              - superset
              - overlap
              - disjoint
            default: identity
          description: Single relation filter. Alias for relations.
          example: identity
        - in: query
          name: minConfidence
          schema:
            type: number
            minimum: 0
            maximum: 1
            default: 0
        - in: query
          name: venues
          schema:
            type: string
          description: Comma-separated venue allow-list.
          example: polymarket,kalshi
        - in: query
          name: excludeVenues
          schema:
            type: string
          description: Comma-separated venue deny-list.
        - in: query
          name: minVenues
          schema:
            type: integer
            minimum: 0
          description: Minimum number of venues required in a cluster.
        - in: query
          name: withOrderbook
          schema:
            type: boolean
            default: false
          description: Require at least one live orderbook on each matched edge.
        - in: query
          name: updatedSince
          schema:
            type: string
            format: date-time
          description: Only include matches updated after this timestamp.
        - in: query
          name: includeRawMatches
          schema:
            type: boolean
            default: false
          description: Include the pairwise match edges used to build each cluster.
        - in: query
          name: sort
          schema:
            type: string
            enum:
              - volume
              - confidence
            default: volume
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 500
            default: 50
        - in: query
          name: offset
          schema:
            type: integer
            minimum: 0
            default: 0
        - in: query
          name: edgeLimit
          schema:
            type: integer
            minimum: 1
          description: Maximum number of pairwise edges to scan before clustering.
      responses:
        '200':
          description: Matched event clusters.
      x-codeSamples:
        - lang: python
          label: Python
          source: |
            import pmxt

            router = pmxt.Router(pmxt_api_key="YOUR_PMXT_API_KEY")
            clusters = router.fetch_matched_event_clusters(
                query="Satoshi",
                relation="identity",
                min_venues=2,
                include_raw_matches=True,
                limit=5,
            )

            for cluster in clusters:
                venues = [event.source_exchange for event in cluster.events]
                print(cluster.canonical_title, venues)
        - lang: javascript
          label: TypeScript
          source: |
            import { Router } from "pmxtjs";

            const router = new Router({ pmxtApiKey: "YOUR_PMXT_API_KEY" });

            async function main() {
              const clusters = await router.fetchMatchedEventClusters({
                query: "Satoshi",
                relation: "identity",
                minVenues: 2,
                includeRawMatches: true,
                limit: 5,
              });

              for (const cluster of clusters) {
                console.log(
                  cluster.canonicalTitle,
                  cluster.events.map((event) => event.sourceExchange),
                );
              }
            }

            main();
        - lang: bash
          label: curl
          source: |
            curl -G "https://api.pmxt.dev/v0/matched-event-clusters" \
              -H "Authorization: Bearer $PMXT_API_KEY" \
              --data-urlencode "query=Satoshi" \
              --data-urlencode "relation=identity" \
              --data-urlencode "minVenues=2" \
              --data-urlencode "includeRawMatches=true" \
              --data-urlencode "limit=5"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        Required when calling the hosted API directly (curl, requests, fetch).
        SDK users pass credentials via constructor params instead.

````