Events & series
How markets group into events and series, and which venues have the concept at all.
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.