GET /api/events — Search upcoming events
Upcoming events in one metro (city), around a point (near), or for one niche tag in every metro (tag with no city), filtered and chronological by default.
| Parameter | Type | Description |
|---|---|---|
city | string albuquerque · ann-arbor · asheville · atlanta · austin · baltimore … (134 values) | Metro slug (or name). One of 90 metros (US and UK) plus 44 API-only metros in Europe. Required unless near, tag (or venue/ids) is given: no city, no near and no tag is a 400 missing-city, an unknown one a 400 unknown-city — there is no default metro. With tag, a comma list (city=berlin,hamburg) narrows the tag search to those metros. |
when | string | Date window, resolved in the metro's own time zone — or one day as YYYY-MM-DD. |
date_from | string (date) | Inclusive start day (YYYY-MM-DD) of an explicit window; used when when is absent. Defaults to today. A multi-day run (end_date) that started earlier but is still on is included. |
date_to | string (date) | Inclusive end day (YYYY-MM-DD) of an explicit window; used when when is absent. Open-ended when omitted. |
updated_since | string (date-time) | Incremental sync: only events changed at or after this ISO-8601 instant, delisted ones included (is_deleted: 1). Pass the previous response's meta.synced_at. |
cat | string | Comma list of category slugs. literary also matches everything at bookstores and libraries. |
free | string 1 | Free events only. |
paid | string 1 | Paid events only. |
max | number | Maximum price in the city's local currency (USD for US metros, GBP for London, EUR/CHF/PLN in the API-only European metros; events with a parsed price). |
tod | string | Comma list of times of day. |
region | string | Neighborhood / sub-area inside the metro, e.g. Cambridge. |
q | string | Free text, matched word by word (up to 4 words; every word must match): event title, venue name, neighbourhood/town, description, performer and author names, and linked book titles. Common words like "the" and "in" are ignored. |
performer | string | Substring match on performer names only. |
series_id | string | Every upcoming occurrence of one series (an event's series_id). |
authors | string 1 | Only events with a known author on the bill. |
near | string | Proximity search: <lat>,<lng>. Orders by distance and overrides sort. The radius spans metros (a point between Washington and Baltimore returns both; each event's city says which); city then only sets the time zone for "today", and defaults to the metro nearest the point. |
radius_km | number | Radius for near (default 25, max 200). |
sort | string featured · date | date is chronological; featured is the site's editorial ranking. |
collapse | string 0 · 1 | 0 = one row per date for every series. By default a DENSE series — at least 5 upcoming dates, on at least 50% of the days from its first to its last (a daily ranger tour, a twice-daily flag ceremony) — is listed once: its first date that matches the filters, with collapsed: 1 and series_first / series_last. Same-day repeats fold into that row. Weekly events are never collapsed; meta.total counts what is listed. Never applied with series_id, ids or updated_since. |
tag | string forro | A niche tag, finer than a category: forro (Forró; related: baião, xote, arrasta-pé, pé de serra, forrobodó). With a city it narrows that metro. WITHOUT a city (and no near) it searches EVERY metro at once, API-only ones included: when / date_from / date_to are then read in each event's own metro time zone, meta.city is null and each row carries its country and currency. An unknown tag is a 400 unknown-tag. |
page | integer | 1-based page of limit rows (100 when no limit). Ignored by the playground server. |
limit | integer | Rows per call (max 500; 100 from Nov 15, 2026). The playground server caps this at 5 (100 signed in). |
venue | string (uuid) | A venue uuid: upcoming events at that venue (the metro comes from the venue). |