> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomry.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List Catalog Events
> Page the cross-organization catalog of live public events
# List Catalog Events
Returns a cursor-paginated list of live, public, discoverable events from **every organizer on Gomry**.
Requires `catalog: read`. Unlike the rest of this API, this endpoint is not scoped to your organization — see [Agentic Commerce](/commerce/introduction).
## Query Parameters
Events per page. Maximum `100`.
Opaque. Pass `pagination.next_cursor` back verbatim — never construct one.
Filter by venue city.
ISO-3166 country name or code, matched case-insensitively.
ISO 8601 datetime. Only events starting at or after this instant.
ISO 8601 datetime. Must be at or after `starts_after`.
Three-letter currency code. **Required whenever you send `min_price` or `max_price`.**
Minimum ticket price in major units. Requires `currency`.
Maximum ticket price in major units. Requires `currency`, and must be at or above `min_price`.
`true` or `false`. Filters to free or paid events.
Substring match on name and description. Up to 200 characters.
`currency` is mandatory alongside a price bound. Without it, `max_price=50` would compare 50 EUR against 50 USD against 50 GBP across a mixed-currency catalog and return results you cannot detect as wrong. Prices are not converted to a base currency on this endpoint.
## Response
Event identifier. Always a string — never assume numeric.
Event name.
Event description.
The canonical, buyable event page. Safe to send a buyer to.
ISO 8601 instant in UTC.
IANA timezone.
Same shape as `start`.
Venue name.
Street address.
City.
State or province.
Country.
Latitude.
Longitude.
`physical`, `virtual`, or `null` when undetermined. Treat `null` as unknown, not as physical.
Cover image URL.
Cheapest ticket in major units. **`null` means unknown, never free.**
Most expensive ticket. Same rule.
ISO 4217 code.
Only `true` on a real zero.
`on_sale`, `sold_out`, `not_yet_open`, `closed`, or `unknown`.
When sales open, if they have not yet.
Organizer-assigned categories.
Organizer identifier.
Organizer name. This is the seller.
Always `null` here. Use the [detail endpoint](/api-reference/catalog/get-catalog-event).
Always `null` here. Use the detail endpoint.
Pass to `cursor` for the next page. `null` means the catalog ends here.
Whether more pages follow.
There is deliberately **no `total`**. A cross-organization count is not knowable without a full scan, and a number that is either expensive or wrong is worse than an authoritative end signal.
## Paging correctly
**`next_cursor: null` is the only end-of-catalog signal.** An empty `data` array mid-catalog is a page where every event failed the eligibility gate — not a terminator. A consumer that stops on an empty page silently truncates its sweep and never notices.
```javascript Sweeping the whole catalog theme={null}
let cursor = null;
const events = [];
do {
const url = new URL("https://www.gomry.com/api/v1/catalog/events");
url.searchParams.set("limit", "100");
if (cursor) url.searchParams.set("cursor", cursor);
const res = await fetch(url, { headers: { "X-API-KEY": key } });
if (!res.ok) throw new Error(`Catalog page failed: ${res.status}`);
const page = await res.json();
events.push(...page.data);
cursor = page.pagination.next_cursor; // the ONLY stop condition
} while (cursor);
```
Errors always leave as a non-2xx. We never answer a failure with an empty page and a null cursor, because that would assert "the catalog ends here" and make an outage look like a shrinking catalog.
## Event price vs ticket type prices
There are two layers, and you will use both.
**Event level** — `price` and `availability`, on every list row. `price` is a range, not a single number: `min` is the cheapest way in ("from \$25"), `max` the dearest. `availability` is one verdict for the whole event. Use these to search, rank, filter and display.
**Ticket type level** — `ticket_types[]`, each with its own `price` and `available`. These are the things a buyer actually orders, and `ticket_types[].id` is what you reference when building an order. They are returned by the [detail endpoint](/api-reference/catalog/get-catalog-event) only; on this endpoint `ticket_types` is always `null`.
When the event range is derived from live ticket classes, only types a buyer could buy **right now** count toward it. Anything not on sale, anything outside its sales window, and donation or pay-what-you-want types (which have no single price to quote) are excluded — so the "from" price is never one checkout would refuse.
The two layers are computed at different moments and, for sellers whose inventory lives behind their own API, by different paths. On a fast-moving event they can differ slightly — a tier can sell out between your list call and your detail call.
Treat the event range as the number you **display**, and the ticket type's own `price` as the number you **charge against**. If they disagree, the ticket type is authoritative.
## Understanding `unknown`
`availability: "unknown"` means we could not determine it. It is **not** a synonym for `on_sale`. Treat it as "check the event page" — never as a green light to sell.
Likewise `price.min: null` means the price is unknown, not that the event is free. `is_free: true` is the only statement that a ticket costs nothing.
Both are uncommon: `price` and `availability` are resolved from live ticket classes, so a populated value is the normal case. You will still see `unknown` or a `null` price where an event has nothing we can read a price from — and you should keep handling both, because they are the honest answer rather than a guess.
```bash cURL theme={null}
curl -H "X-API-KEY: your_api_key" \
"https://www.gomry.com/api/v1/catalog/events?limit=50&city=New%20York"
```
```javascript JavaScript theme={null}
const res = await fetch(
"https://www.gomry.com/api/v1/catalog/events?limit=50&city=New+York",
{ headers: { "X-API-KEY": "your_api_key" } }
);
const { data, pagination } = await res.json();
```
```python Python theme={null}
import requests
res = requests.get(
"https://www.gomry.com/api/v1/catalog/events",
headers={"X-API-KEY": "your_api_key"},
params={"limit": 50, "city": "New York"},
)
page = res.json()
```
```json 200 theme={null}
{
"data": [
{
"id": "AbCdEfGhIjKlMnOpQrSt",
"name": "Summer Tech Conference 2026",
"description": "A two-day conference covering the latest in tech.",
"url": "https://www.gomry.com/event/summer-tech-conference-2026-AbCdEfGhIjKlMnOpQrSt",
"start": { "utc": "2026-07-15T14:00:00.000Z", "timezone": "America/New_York" },
"end": { "utc": "2026-07-16T22:00:00.000Z", "timezone": "America/New_York" },
"venue": {
"name": "Convention Center",
"address": "123 Main St",
"city": "New York",
"state": "NY",
"country": "US",
"latitude": 40.7128,
"longitude": -74.006
},
"location_type": "physical",
"cover_image": "https://storage.googleapis.com/...",
"price": { "min": 79.0, "max": 249.0, "currency": "USD", "is_free": false },
"availability": "on_sale",
"sales_start": null,
"categories": ["Technology"],
"organization": { "id": "OrgAbCdEfGhIjKlMnOpQ", "name": "Tech Events Co" },
"ticket_types": null,
"registration_questions": null
}
],
"pagination": {
"next_cursor": "eyJlbmQiOiIyMDI2LTA3LTE2VDIyOjAwOjAwWiJ9",
"has_more": true
}
}
```