Skip to main content
The same real-world question is listed separately on every venue. Discovery returns those listings as one matched cluster. Which id to store is Ids.

​
What a cluster is

A cluster is a set of venue events AGG has decided are the same real-world event, plus the market and outcome pairings between them.
Each level is symmetric: you get the whole set no matter which member you started from. You consume the cluster on the response. You do not rebuild it.

​
Cluster fields

venues[] is how many venues. matchedVenueEvents[] is which events. Do not enumerate members by walking the list preview of venueMarkets[]. That preview is up to three markets, and a member with no matched market never appears there. Cross-venue prices hang off matchedVenueMarkets[]. The walk is Comparing prices. Live depth is the orderbook socket, which takes an outcome id.

​
Look up by external identifier

Filtering venue plus externalIdentifier returns that venue’s row, not the cluster anchor. The same cluster is reachable from any member. GET /venue-events accepts the same pair. List venue events. getVenueEvents does not send externalIdentifier. The SDK call for this lookup is getVenueMarkets.
List venue markets. matchedVenueMarkets[] is the same market on the other venues. A cluster can contain two markets from the same venue. Kalshi lists a head-to-head as one market per team, and both can be matched, so two Kalshi rows in one cluster are not a duplicate. GET /venue-market-outcomes takes externalIdentifier. venue is optional there and only narrows. There is no dedicated SDK method. client.request can call it. Look up venue market outcomes by external identifier. The page returns id pairs on matchedVenueMarketOutcomes[] and identity fields on page-level matchedVenueMarkets[]. Rules text is not on that response.
  • venue is required on /venue-events and /venue-markets. Omitting it returns 400.
  • Repeat externalIdentifier for up to 20 values. More than 20 returns 400.
  • Unknown identifiers are omitted, not returned as nulls. Match rows back by externalIdentifier.
  • Kalshi puts its ticker on the Yes outcome only. The No outcome has no identifier. Fetch the market and read venueMarketOutcomes[].
An empty matchedVenueEvents[] can be a companion rather than a miss. See Companion events.

​
Anchor and member rows

GET /venue-events/{id} returns the row you asked for. It does not promote a member id to the anchor. Cluster fields are complete from either row. The member’s own markets, title, description, image, and slug are that venue’s copy.

​
Market lists: preview vs full

The venueMarkets array on a list item is a preview of up to three markets, not the largest and not the full set. Use marketCount for the count. Fetch markets from List venue markets with venueEventId. venueEventId is cluster-scoped by default (cluster=true). You get every venue’s markets for that real-world event, with matched siblings folded into one anchor row, each still carrying matchedVenueMarkets[]. Naming any member returns the same page. It is also how you reach a market that exists on only one venue. cluster=false is that one venue event’s own markets. Pass the same value to GET /venue-events/{id} when you want marketCount to match. Only the strings true and false are accepted. Any other value is 400, not the default. marketCount counts the open rows that cluster-scoped GET /venue-markets?venueEventId= returns. Pass status=open on the market list to see that set. Without status, the list also returns closed and resolved markets. Rolled-up volume sums every market in the cluster, including siblings folded out of the list. The two totals are not over the same set. The embedded market array on event detail is deprecated and is always that one event’s markets, whatever cluster says.

​
Companion events: why a cluster can look empty

A venue often splits one game into a base plus companions such as … - More Markets or … : Spread. They share one aggKey and each has its own id. Two events from the same venue never share a cluster, except Hyperliquid deployers. A companion clusters with the other venues’ equivalent companions, not with the game. matchedVenueEvents[] can be empty while the game is live on several venues. groupParentId non-null is how you tell.
Follow groupParentId, or fetch GET /venue-events?aggKey={aggKey} for every companion of that game. The game page uses the key fetch. See Sports market detail and aggKey. Each market still carries matchedVenueMarkets[] on a companion, so a price comparison does not need matchedVenueEvents[]. grouped=true on the event list folds companions under their base. It is opt-in, because it hides the companions a game page loads again with aggKey.

Ids

Which id to store, and which id is only the anchor for this page.

Comparing prices

Walk matched markets and read midpoints.

Orderbook socket

Live depth, keyed by outcome id.

aggKey

Optional fetch filter when the key converges.

Settlement differences

Resolution-criteria differences between venues in a cluster.