Event instances

Use these endpoints to power calendars, "what's on" feeds, and event detail widgets in a theme or embedded site.

By default the list endpoint returns published, future event instances for the current site, sorted by start date.

List event instances

GET {your-domain}/api/event-instances.json

Query parameters

Parameter	Type	Default	Description
`page`	integer	`1`	Page number to return.
`limit`	integer	`500`	Page size. Cap depends on the endpoint; very large limits may be clamped.
`showPast`	boolean	`false`	When `true`, includes instances whose start date has already passed.
`tenant`	string	(current site)	Slug of a tenant to filter by, when the requesting site has access to multiple. Most calls can omit this.
`depth`	integer (0–5)	`2`	How deeply to expand related records (event, venue, series, etc.). Higher values return more inline data; lower values are faster.
`select`	string	—	Comma-separated dotted field paths to narrow the response. See Field selection.

Response

A standard paginated list:

{
  "docs": [
    {
      "id": "67be2c1cb1d3f...",
      "startDate": "2026-06-12T19:30:00.000Z",
      "startDate_tz": "Europe/London",
      "startDateLocalAsUTC": "2026-06-12T19:30:00.000Z",
      "event": {
        "id": "...",
        "title": "La Traviata",
        "slug": "la-traviata",
        "url": "/events/la-traviata",
        "image": { "url": "https://..." },
        "description": "...",
        "venue": { "title": "Main Stage", "slug": "main-stage" },
        "series": null,
        "season": null
      },
      "venue": { "id": "...", "title": "Main Stage", "slug": "main-stage" },
      "series": null,
      "ticketingSystem": "tessitura",
      "booking": { "url": "https://..." },
      "tessitura": { "performanceId": "...", "availability": "available" }
    }
  ],
  "totalDocs": 42,
  "limit": 500,
  "totalPages": 1,
  "page": 1,
  "pagingCounter": 1,
  "hasPrevPage": false,
  "hasNextPage": false,
  "prevPage": null,
  "nextPage": null
}

Per-instance fields you can rely on:

Field	Description
`id`	Unique identifier.
`startDate`	ISO timestamp in UTC.
`startDate_tz`	IANA timezone for the venue.
`startDateLocalAsUTC`	The local wall-clock time, encoded as UTC. Useful for grouping by calendar day in the venue's timezone without timezone conversion in your code.
`event`	The parent event — title, slug, url, image, description, venue, series, season.
`venue`, `series`	Related records set on the instance (when present). The season comes through the parent `event`.
`ticketingSystem`	One of `tessitura`, `spektrix`, `elevent`, or `null`.
`booking.url`	Direct booking link, when configured.
`tessitura`, `spektrix`, `elevent`	Ticketing-system-specific data, present when that integration is installed.

The event object also carries rendered-HTML companions for its rich-text fields — richTitle_html and richDescription_html alongside title and description — so you can drop ready-to-render markup straight into a calendar card.

Custom data on event feeds

Event instance responses can include custom attributes from the instance, the parent event, and related records such as the venue. When you request a deeper response, those custom attributes may include relationships to pages, media, files, or custom objects.

Each relationship-style custom attribute has a Public API response setting:

Setting	Response shape
Full record	Returns the expanded related record when the requested `depth` includes it.
Summary	Returns a compact object with identifying fields such as `id`, `title`, `name`, `label`, `slug`, or `url`.
Reference only	Returns only the related record ID, or an array of IDs for fields that allow multiple values.

Use ?select= together with Summary or Reference only for calendar feeds that need custom data but do not need every field from every related record.

Examples

Fetch the next 10 upcoming instances:

const res = await fetch('/api/event-instances.json?limit=10');
const { docs } = await res.json();

Paginate through everything (including past dates):

async function* allInstances() {
  let page = 1;
  while (true) {
    const res = await fetch(`/api/event-instances.json?page=${page}&limit=200&showPast=true`);
    const data = await res.json();
    yield* data.docs;
    if (!data.hasNextPage) break;
    page += 1;
  }
}

Get an event instance by ID

GET {your-domain}/api/event-instances/{id}

Returns the instance wrapped in a doc key: { "doc": { ... } }. The record inside has the same field shape as items in the list response.

Path parameters

Parameter	Type	Description
`id`	string	The instance ID, taken from a list response or a relationship field on another record.

Errors

Status	Meaning
`400`	The `id` is missing or not a valid identifier.
`404`	No instance with that ID exists, or your site doesn't have access to it.
`500`	Server error.

Field selection

Pass ?select= with a comma-separated list of dotted field paths to drop everything else. The pagination wrapper is always returned in full; only items inside docs are narrowed.

?select=startDate,event.title,event.url,venue.title

Use field selection to keep payloads small for calendar grids that only need the date, the event title, and a link.

Caching

When edge caching is enabled for your site, list responses can be served from the edge. Avoid request-uniqueness query parameters that vary per visitor (cache-busters, timestamps) unless you genuinely need a fresh response. The cache invalidates automatically when an editor publishes, schedules, or deletes an event instance.

On this page