Events & series

Three levels of grouping exist in the catalog, and confusing them is a common source of integration bugs. Prediction markets, briefly defines the terms; this page covers the verbs.

Level	What it is	Verbs
Market	One question, holding its outcomes	fetchMarkets, fetchMarket
Event	A group of related markets	fetchEvents, fetchEvent, fetchEventMetadata
Series	A recurring group of events	fetchSeries

Order books and candles key on the outcome, one level below all of these. Selecting an outcome is always the last step before asking for depth or history.

Events

An event ties related markets together — an election with a market per candidate, or a fixture with a market per result. Reading at the event level is how you get the whole question rather than one slice of it.

curl -s "$PREDICTEFY_API_URL/api/router/fetchEvents?query=election&status=active&limit=10" \
  -H "Authorization: Bearer pk_live_YOUR_KEY"

fetchEvents accepts the same list parameters as fetchMarkets — limit, cursor, status, query, category — and paginates the same way.

Series

A series is a recurring grouping: the same question asked on a schedule, such as a monthly rate decision. fetchSeries is catalog-derived rather than venue-published.

Not every venue has the concept. On a venue without it, fetchSeries returns an empty list rather than an error — the request succeeded and the answer is that this venue does not organise markets that way. Do not treat an empty series list as a failure.

Venue-native event metadata

fetchEventMetadata returns the venue’s own metadata for a single event. It is Kalshi-only and not available on router — it exposes a venue-native structure that has no cross-venue equivalent, so there is nothing sensible for the router to union.

Calling it on another venue returns an honest NOT_SUPPORTED rather than an empty object.

Choosing the right level

• Use markets when you want one question and its prices.
• Use events when you want a whole contest, and when you want to avoid showing a user one candidate’s market without its siblings.
• Use series to find recurring questions over time, then read the events within them.
• Use matched clusters when you want the same real-world question across different venues — that is a different relationship from an event, and is Predictefy’s own matching rather than a venue’s grouping.