---
title: "Search venues"
method: GET
path: "/v1/venues"
tags: ["Events"]
---

# Search venues

`GET /v1/venues`

## Request

- Base URL: `https://api.ufcalendar.com`
- URL: `https://api.ufcalendar.com/v1/venues`
- Auth: HTTP bearer

Arenas and venues that have hosted (or have booked) a launch-org event, alphabetical. `q` (at least 2 characters) matches the name or the city, accent-insensitive; `country` takes an ISO-2 code (`US`) or an English country name (`Brazil`). Each row is `id`, `slug`, `name`, `city`, `region`, `country`, `tz`, `capacity` — pass the `id` to `/v1/venues/{id}/events` for what was fought there. A `q` under 2 characters 400s `invalid_query`.

## Query parameters

- `q` string
- `country` string
- `cursor` string
- `limit` integer

## Response `200`

Venues, alphabetical

- VenuesPageResponse: Alphabetical by name.
  - `data` VenueListItem[], required
    - `id` integer, required
    - `slug` string, nullable, required
    - `name` string, required
    - `city` string, nullable, required
    - `region` string, nullable, required
    - `country` string, nullable, required
    - `tz` string, nullable, required
    - `capacity` integer, nullable, required
  - `meta` object, required
    - `pagination` CursorPagination, required: Cursor pagination WITHOUT the applied `limit` (the newer list routes — changes, fight search, splits, venues, articles — do not echo it).
      - `next_cursor` string, nullable, required: Opaque; pass as `?cursor=`. Null on the last page.
      - `has_more` boolean, required
    - `ignored_params` string[]: Present only when the request carried query parameters this endpoint does not take — they were ignored. Same list as the `X-UFCalendar-Ignored-Params` header. Sorted, unique.

## Other responses

- `304`: Not Modified — `If-None-Match` matched the current weak `ETag`. Empty body.
- `400`: Invalid input (`invalid_query`, `invalid_country`).
- `401`: Missing/invalid API key (`unauthorized`).
- `403`: No active plan on the key's account (`subscription_required`) — choose a plan or start the free 1-day trial at https://www.ufcalendar.com/account/api.
- `404`: Not found (`not_found`; staged-org data 404s until the org is promoted).
- `429`: Rate limited (`rate_limited`) or monthly quota reached (`quota_exceeded`). Honor `Retry-After`.
- `500`: Something broke on our side (`internal_error`). It has been logged under the `request_id`.

---

[API](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api.md) · [All operations](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ufcalendar/apis/ufcalendar-fight-api/revisions/9623cc8fb70b?raw)