> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.todaytixgroup.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.todaytixgroup.com/_mcp/server.

# List events

GET https://stg.ttix.io/api/v3/events

Returns a paginated list of events in a location. Pass `query` to narrow the list to events matching a search term.

Reference: https://docs.todaytixgroup.com/api-reference/browse/events/get-events

## Authentication

- `X-TT-API-Key` header (required) — API Key authentication via header

## Servers

- `https://stg.ttix.io` (Staging Environment, default)
- `https://api.ttix.io` (Production Environment)

## Request

### Query parameters

- `locationId` (string, required) — Location ID to filter events by
- `query` (string, optional) — Free-text search across event name, venue, category, cast and search keywords. Combines with locationId. Omit it, or send it blank, for the unfiltered catalog.
- `limit` (integer, optional, default: 50) — Maximum number of results to return.
- `offset` (integer, optional, default: 0) — Number of results to skip for pagination.

### Headers

- `X-TT-Retailer` (string, required) — Your retailer identifier, provided during onboarding. It must be a retailer your API key was issued for.
- `X-TT-Platform` (enum, required) — Identifies the platform the request comes from.
  - Allowed values: `android`, `api`, `ios`, `web`

## Response

### 200

Paginated list of events.

- `data` (list of EventResponse, optional) — List of entities in the current page.
- `pagination` (PaginationInfo, optional) — Pagination metadata.

## Errors

### 400 Bad Request Error

A missing `locationId` or one that is not a positive whole number, a `query` longer than 50 characters, or invalid pagination parameters.

- `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display.

### 401 Unauthorized Error

The request could not be authenticated. Any request gets `UNAUTHORIZED` when the `X-TT-API-Key` header is missing, and `INVALID_API_KEY` when the key is not valid or was revoked, or when the `X-TT-Retailer` header is missing or names a retailer the key cannot be used for.

- `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display.

### 403 Forbidden Error

The request is not allowed from where it was sent. Any request sent from a web page gets `ORIGIN_NOT_ALLOWED` when the page's origin is not one the API key allows. Add the origin to the key, or use a key that allows it. A request with no `Origin` header, such as one from your server, is never refused for this.

- `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display.

### 429 Too Many Requests Error

Too many requests. Wait at most the number of seconds in the `Retry-After` header when it is present, then send the request again.

- `error` (ErrorResponse, required) — What went wrong: `type` and `code` for your code to act on, `message` to display.

## Types

### EventResponse

An event, with its run dates, location, order limit and price summary.

- `id` (string, required) — Event ID.
- `name` (string, required) — Full title of the event.
- `orderLimit` (OrderLimitResponse, required) — Bounds on the ticket quantity a single order may contain. Applies to every occurrence.
- `productType` (enum, required, nullable) — Classification of the product sold for this event. Null when the classification is unknown.
  - Allowed values: `ATTRACTION`, `BUS_TOUR`, `GIFT_CARD`, `SHOW`, `STREAMING`
- `endDate` (string, optional, nullable) — End date of the event run (ISO 8601 yyyy-MM-dd). Null for open-ended runs.
- `fromPrice` (Money, optional, nullable) — Lowest regular ticket price currently on sale across all occurrences, in the event's own currency. Null when no regular tickets are on sale; it says nothing about why.
- `location` (LocationSimpleResponse, optional, nullable) — Location where the event takes place.
- `maxDiscountPercentage` (integer, optional) — Best discount currently on sale across all occurrences, as a whole-number percentage. Omitted when there is no discount, or when the event does not present savings as a percentage.
- `slug` (string, optional, nullable) — URL-friendly identifier for the event, used as the path segment in TodayTix web links. Null when the event has none.
- `startDate` (string, optional, nullable) — Start date of the event run (ISO 8601 yyyy-MM-dd). Null when not yet announced.

### PaginationInfo

Pagination information for paginated responses

- `limit` (integer, optional) — Maximum number of results per page
- `offset` (integer, optional) — Number of results skipped for pagination
- `total` (long, optional) — Total number of results available

### ErrorResponse

What went wrong: `type` and `code` for your code to act on, `message` to display.

- `type` (enum, required) — High-level error category.
  - Allowed values: `INVALID_REQUEST_ERROR`, `AUTHENTICATION_ERROR`, `PAYMENT_ERROR`, `PERMISSION_ERROR`, `NOT_FOUND_ERROR`, `METHOD_NOT_ALLOWED_ERROR`, `CONFLICT_ERROR`, `RESOURCE_GONE_ERROR`, `PRECONDITION_FAILED_ERROR`, `UNSUPPORTED_MEDIA_TYPE_ERROR`, `PRECONDITION_REQUIRED_ERROR`, `RATE_LIMIT_ERROR`, `API_ERROR`, `SERVICE_UNAVAILABLE`
- `code` (enum, required) — Machine-readable error code.
  - Allowed values: `METHOD_NOT_ALLOWED`, `UNSUPPORTED_MEDIA_TYPE`, `INVALID_FIELD_VALUE`, `ACCESS_CARD_NOT_VERIFIED`, `ACCESS_CARD_WRONG_SCHEME`, `ACCESS_VERIFICATION_NOT_SUPPORTED`, `ACCESS_VERIFICATION_UNAVAILABLE`, `TICKET_ALERT_SIGNUP_NOT_SUPPORTED`, `MIXED_ITEM_TYPES_NOT_SUPPORTED`, `INVALID_VOUCHER`, `CURRENCY_NOT_SUPPORTED`, `CURRENCY_TEMPORARILY_UNAVAILABLE`, `MISSING_REQUIRED_HEADER`, `MISSING_REQUIRED_FIELD`, `UNAUTHORIZED`, `INVALID_API_KEY`, `INVALID_ACCESS_TOKEN`, `PAYMENT_AUTHENTICATION_REQUIRED`, `PAYMENT_DECLINED`, `RISK_CHECK_FAILED`, `APPLE_PAY_NOT_AVAILABLE`, `APPLE_PAY_SESSION_UNAVAILABLE`, `INVALID_REQUEST`, `RESOURCE_NOT_FOUND`, `INSUFFICIENT_PERMISSIONS`, `ORIGIN_NOT_ALLOWED`, `RATE_LIMITED`, `INTERNAL_SERVER_ERROR`, `SERVICE_UNAVAILABLE`, `PRICE_CHANGED`, `INVENTORY_EXHAUSTED`, `OCCURRENCE_NOT_AVAILABLE`, `OCCURRENCE_NOT_COMPATIBLE`, `ORPHANED_SEATS`, `INVALID_PRICE_OPTION`, `MIXED_OCCURRENCES_NOT_SUPPORTED`, `EVENT_NOT_SELLABLE`, `MIXED_PRODUCT_TYPES_NOT_SUPPORTED`, `MULTIPLE_GIFT_CARDS_NOT_SUPPORTED`, `GIFT_CARD_QUANTITY_NOT_SUPPORTED`, `MINIMUM_QUANTITY_NOT_MET`, `EVENT_MINIMUM_NOT_MET`, `VOUCHER_NOT_APPLICABLE_TO_GIFT_CARD`, `CART_EXPIRED`, `EXPECTED_TOTAL_MISMATCH`, `TICKET_LIMIT_EXCEEDED`, `PAYMENT_METHOD_NOT_AVAILABLE`, `CART_ALREADY_ORDERED`, `CART_CUSTOMER_REQUIRED`, `CART_ALREADY_CLAIMED`, `INVALID_IDEMPOTENCY_KEY`, `IDEMPOTENCY_KEY_ALREADY_PROCESSING`, `IDEMPOTENCY_KEY_CART_MISMATCH`, `IDEMPOTENCY_KEY_FAILED`, `GRANT_NOT_CLAIMABLE`, `GRANT_NOT_CANCELLABLE`, `WALLET_PASS_DOWNLOAD_BLOCKED`, `ACTION_NOT_AVAILABLE`, `WALLET_PASS_CHANGED`, `WALLET_PASS_NOT_ISSUED`, `WALLET_PASS_REPLACEMENT_NOT_SUPPORTED`, `WALLET_PASS_REPLACEMENT_UNFINISHED`, `WALLET_PASS_REPLACEMENT_NEEDS_SUPPORT`, `VERSION_REQUIRED`, `THIRD_PARTY_OUTAGE`
- `message` (string, required) — Human-readable description of the error.
- `param` (string, optional, nullable) — The request field that caused the error, if applicable.
- `details` (map from string to ErrorResponseDetails, optional, nullable) — Additional structured data for client recovery logic.

### OrderLimitResponse

Bounds on the ticket quantity a single order for this event may contain.

- `max` (integer, required) — Most tickets one order may contain.
- `min` (integer, required) — Fewest tickets one order must contain.

### Money

Monetary amount: an integer in minor units (cents for USD) with its currency code.

- `amount` (long, required) — Amount in minor units (cents for USD, pence for GBP, etc.)
- `currency` (string, required) — ISO 4217 currency code

### LocationSimpleResponse

The location an event takes place in.

- `id` (string, required) — Location ID.
- `name` (string, required) — Display name of the location.
- `country` (string, required) — ISO 3166-1 alpha-2 country code.
- `slug` (string, required) — URL-friendly identifier for the location, used as the path segment in TodayTix web links.

### ErrorResponseDetails

Additional structured data for client recovery logic.

## Examples

**Response**

```json
{
  "data": [
    {
      "id": "456",
      "name": "Hamilton",
      "orderLimit": {
        "max": 8,
        "min": 1
      },
      "productType": "SHOW",
      "endDate": "2026-12-31",
      "fromPrice": {
        "amount": 8900,
        "currency": "USD"
      },
      "location": {
        "id": "1",
        "name": "New York",
        "country": "US",
        "slug": "nyc"
      },
      "maxDiscountPercentage": 25,
      "slug": "hamilton-broadway",
      "startDate": "2026-03-01"
    },
    {
      "id": "457",
      "name": "The Phantom of the Opera",
      "orderLimit": {
        "max": 6,
        "min": 1
      },
      "productType": "SHOW",
      "endDate": null,
      "fromPrice": {
        "amount": 3500,
        "currency": "GBP"
      },
      "location": {
        "id": "2",
        "name": "London",
        "country": "GB",
        "slug": "london"
      },
      "slug": "the-phantom-of-the-opera",
      "startDate": "2026-05-15"
    }
  ],
  "pagination": {
    "limit": 50,
    "offset": 0,
    "total": 2
  }
}
```

**SDK Code**

```python Events_getEvents_example
import requests

url = "https://stg.ttix.io/api/v3/events"

querystring = {"locationId":"1","query":"hamilton","limit":"50","offset":"0"}

headers = {
    "X-TT-Retailer": "YOUR_RETAILER_ID",
    "X-TT-Platform": "android",
    "X-TT-API-Key": "<apiKey>"
}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```javascript Events_getEvents_example
const url = 'https://stg.ttix.io/api/v3/events?locationId=1&query=hamilton&limit=50&offset=0';
const options = {
  method: 'GET',
  headers: {
    'X-TT-Retailer': 'YOUR_RETAILER_ID',
    'X-TT-Platform': 'android',
    'X-TT-API-Key': '<apiKey>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Events_getEvents_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://stg.ttix.io/api/v3/events?locationId=1&query=hamilton&limit=50&offset=0"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-TT-Retailer", "YOUR_RETAILER_ID")
	req.Header.Add("X-TT-Platform", "android")
	req.Header.Add("X-TT-API-Key", "<apiKey>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Events_getEvents_example
require 'uri'
require 'net/http'

url = URI("https://stg.ttix.io/api/v3/events?locationId=1&query=hamilton&limit=50&offset=0")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-TT-Retailer"] = 'YOUR_RETAILER_ID'
request["X-TT-Platform"] = 'android'
request["X-TT-API-Key"] = '<apiKey>'

response = http.request(request)
puts response.read_body
```

```java Events_getEvents_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://stg.ttix.io/api/v3/events?locationId=1&query=hamilton&limit=50&offset=0")
  .header("X-TT-Retailer", "YOUR_RETAILER_ID")
  .header("X-TT-Platform", "android")
  .header("X-TT-API-Key", "<apiKey>")
  .asString();
```

```php Events_getEvents_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://stg.ttix.io/api/v3/events?locationId=1&query=hamilton&limit=50&offset=0', [
  'headers' => [
    'X-TT-API-Key' => '<apiKey>',
    'X-TT-Platform' => 'android',
    'X-TT-Retailer' => 'YOUR_RETAILER_ID',
  ],
]);

echo $response->getBody();
```

```csharp Events_getEvents_example
using RestSharp;

var client = new RestClient("https://stg.ttix.io/api/v3/events?locationId=1&query=hamilton&limit=50&offset=0");
var request = new RestRequest(Method.GET);
request.AddHeader("X-TT-Retailer", "YOUR_RETAILER_ID");
request.AddHeader("X-TT-Platform", "android");
request.AddHeader("X-TT-API-Key", "<apiKey>");
IRestResponse response = client.Execute(request);
```

```swift Events_getEvents_example
import Foundation

let headers = [
  "X-TT-Retailer": "YOUR_RETAILER_ID",
  "X-TT-Platform": "android",
  "X-TT-API-Key": "<apiKey>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://stg.ttix.io/api/v3/events?locationId=1&query=hamilton&limit=50&offset=0")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```