> ## Documentation index
> Fetch the complete documentation index at: https://docs.predictefy.com/llms.txt
> Use it to discover every available page before exploring further.

# 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](/guides/prediction-markets/) 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.

```sh
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](/guides/cross-venue/) 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.