> ## Documentation Index
> Fetch the complete documentation index at: https://docs.eventory.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search filters

> The filterExpression syntax for POST /eventory/data/search and the attributes you can filter on.

`POST /eventory/data/search` accepts a `filterExpression` string that narrows the
results before they are ranked. The expression is passed verbatim to the search
backend, so this page is the reference for what it accepts.

## Syntax

Each clause is an `attribute:value` pair. Quote values that contain spaces. Combine
clauses with `AND`, `OR` and `NOT`, and group with parentheses. Numeric attributes
also accept comparison operators and a closed range.

```
venue_country_code:US
venue_country_code:US AND tickets_sold > 1000
(venue_country_code:US OR venue_country_code:CA) AND event_date >= 1767225600
NOT category_name:"Sports"
average_ticket_price_sold: 50 TO 200
artist_name:"Teddy Swims" AND available_tickets > 0
```

| Operator                   | Applies to | Example                                |
| -------------------------- | ---------- | -------------------------------------- |
| `attribute:value`          | any        | `venue_city:London`                    |
| `=` `!=` `<` `<=` `>` `>=` | numeric    | `capacity >= 10000`                    |
| `attribute:lower TO upper` | numeric    | `event_date: 1767225600 TO 1769904000` |
| `AND` `OR` `NOT` `( )`     | any        | `NOT category_name:"Sports"`           |

## Filterable attributes

| Attribute                   | Type   | Notes                                                        |
| --------------------------- | ------ | ------------------------------------------------------------ |
| `event_id`                  | int    | Same value as `hits[].event_id`.                             |
| `event_name`                | string | Full title. Quote values with spaces.                        |
| `event_date`                | int    | Unix timestamp in seconds. Use comparisons for date windows. |
| `category_name`             | string | Marketplace category, e.g. `"Concerts"`, `"Sports"`.         |
| `artist_id`                 | int    |                                                              |
| `artist_name`               | string | Quote values with spaces.                                    |
| `venue_id`                  | int    |                                                              |
| `venue_name`                | string | Quote values with spaces.                                    |
| `venue_city`                | string |                                                              |
| `venue_country`             | string | Full name, e.g. `"United States"`.                           |
| `venue_country_code`        | string | ISO 3166 alpha-2, e.g. `US`, `GB`, `IT`.                     |
| `tickets_sold`              | int    | Comparisons supported.                                       |
| `tickets_sold_24h`          | int    | Comparisons supported.                                       |
| `available_tickets`         | int    | Comparisons supported.                                       |
| `capacity`                  | int    | Comparisons supported.                                       |
| `average_ticket_price_sold` | number | Comparisons supported.                                       |

Any field you see on a hit can generally be used as a filter attribute; the list above
is what is reliably supported today.

## Limits and gotchas

* The whole expression is capped at **6000 characters**. Longer requests fail with
  `400 INVALID_REQUEST` before any backend call, and are not billed.
* **Unknown attributes are silently ignored**, not rejected. A typo in an attribute
  name produces an unfiltered result rather than an error, so test a new filter
  against a query you know is non-empty and check that `nbHits` drops.
* Dates are Unix seconds. To filter on a calendar day, compute the timestamp range
  for that day in UTC.

## Sorting and paging

`sortBy` orders the filtered results. `recommended` is the default relevance order;
every other value has an ascending form and a `.desc` form:

```
event_date            event_date.desc
event_name            event_name.desc
average_ticket_price_sold   average_ticket_price_sold.desc
tickets_sold          tickets_sold.desc
tickets_sold_24h      tickets_sold_24h.desc
available_tickets     available_tickets.desc
capacity              capacity.desc
```

`page` is 1-based and `hitsPerPage` is capped at 100. `nbHits` and `nbPages` in the
response tell you how far you can page. Each page is one credit.

## Example

```bash theme={null}
curl -s https://api.eventory.ai/eventory/data/search \
  -H "apikey: $EVENTORY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "",
    "hitsPerPage": 50,
    "sortBy": "tickets_sold_24h.desc",
    "filterExpression": "venue_country_code:GB AND category_name:\"Concerts\" AND event_date >= 1767225600"
  }'
```

An empty `query` with a filter and a sort is the way to ask "what is selling fastest
in the UK right now".