Skip to main content
GET

​
List Catalog Events

Agents: no API key needed. Register a credential yourself in two requests and send it as Authorization: Bearer. See For agents: get a credential yourself.
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.

​
Query Parameters

​
integer
default:"50"
Events per page. Maximum 100.
​
string
Opaque. Pass pagination.next_cursor back verbatim — never construct one.
​
string
Filter by venue city.
​
string
ISO-3166 country name or code, matched case-insensitively.
​
string
ISO 8601 datetime. Only events starting at or after this instant.
​
string
ISO 8601 datetime. Must be at or after starts_after.
​
string
Three-letter currency code. Required whenever you send min_price or max_price.
​
number
Minimum ticket price in major units. Requires currency.
​
number
Maximum ticket price in major units. Requires currency, and must be at or above min_price.
​
boolean
true or false. Filters to free or paid events.
​
string
A keyword or phrase, up to 200 characters: 49ers, jazz in Lisbon. A relevance search with the same engine the site uses (name, venue, organizer, categories and description, plus semantic matches), not a substring filter. Results come back ranked rather than by end time, the other filters apply inside the ranked list, and has_more is true only while ranked results remain, so a keyword page is never empty with a cursor. The cursor is bound to its q: passing it back with a different keyword answers 400 invalid_cursor.
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

​
array
​
object
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.
Sweeping the whole catalog
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 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.