Tools
screen_events
Finds and ranks upcoming events by price, demand and inventory.
When to use it
- You want every event that meets conditions, like concerts in the next month whose median price rose this week.
- You want the top events by one measure, ranked for you.
- You want counts, not rows: which acts play the same venue more than once, which venues have the most shows, how many dates each act has. Set
group_by. - You know the event already: use
search_eventsto find it by name, venue or date, andget_event_analyticsfor all of its numbers.
Inputs
predicate(object, default{}): The conditions, as a predicate: each one names a column, an operator and a value, joined withall(and) orany(or). Leave it out to screen every upcoming event.preset(string): Run a preset screen by its key, liketop_selling_24h, aslist_screen_columnswithviewpresetsgives it: the same rows, in the same order, as the app's preset. Send it instead ofpredicateandsort.view_id(uuid): Run a saved View by its id, aslist_viewsgives it: the events the app shows for that View now, with the View's own floor setting. Send it instead ofpredicateandpreset.sort,columnsand paging still apply.sort(object): The column to rank by, andascordesc, as{ "col": "ea.median_price_pct_7d", "dir": "desc" }.columns(array of strings): The columns each row carries, spelled aslist_screen_columnsgives them. Leave it out for a short default set.group_by(string): Count the matching events instead of listing them: byperformer,venue, orperformer_venue(one act at one venue). The largest groups come first.limitandpagecount groups;sortandcolumnsdo not apply. One ofperformer,venue,performer_venue.min_events(integer): Withgroup_by, leave out groups with fewer events than this.2keeps only repeats. Leave it out for 1.page(integer, default1): The page of results.limit(integer, default50): Rows per page.count(boolean, defaultfalse): Also count every match, up to 10,000. It makes the call slower, so set it only when you need the total.active_only(boolean, defaulttrue): Only events Ticker is tracking now. Setfalseto include inactive events too; their numbers stopped updating.apply_floor(boolean, defaulttrue): Leave out thin events, with few listings or a low median price. Setfalseto screen every event.parking(string, defaulthide): Parking passes sold as their own event:hide(the default) leaves them out,onlyreturns parking alone,includereturns parking beside every other event. Withview_id, the View's own choice runs. One ofhide,include,only.include_past(boolean, defaultfalse): Settrueto screen events that have already taken place as well.falsewhen you leave it out. Past events are on the Max plan and above; on another plantrueis refused.exclude_stale(boolean, defaulttrue): Leave out events whose prices are more than three days old.diagnostics(boolean oron_empty, defaulton_empty): Explain an empty result: how many events each condition kept.on_emptyexplains only an empty page,trueexplains every page,falsenever. It adds a few seconds.
Examples
Which events in the next 30 days have a median price up 20% or more this week?
{
"predicate": {
"all": [
{ "col": "ea.days_to_event", "op": "between", "val": [0, 30] },
{ "col": "ea.median_price_pct_7d", "op": ">=", "val": 20 }
]
},
"sort": { "col": "ea.median_price_pct_7d", "dir": "desc" },
"limit": 25
}Which Zach Bryan shows are losing the most tickets this week?
{
"predicate": {
"all": [{ "col": "p.name", "op": "contains", "val": "Zach Bryan" }]
},
"sort": { "col": "ea.tickets_delta_7d", "dir": "asc" },
"columns": [
"e.event_name",
"e.local_date",
"ea.tickets_delta_7d",
"ea.lowest_aip_price_current"
]
}Which acts play the same venue more than once?
{ "group_by": "performer_venue", "min_events": 2 }What comes back
- One row per event, with
event_id,event_urland the columns you asked for. Passevent_idto any other tool. totalandtotalPageswhencountistrue.- With
group_by: one entry per group with its performer or venue or both (ids, name, city), its number of events, its first and last date, and its first 10 events withevent_url. At most 100,000 events are grouped, the soonest first, andevents_cappedsays when that cut applied. - A
diagnosticsblock on an empty page: how many events each condition kept, and a warning when a column has no values for these events. - A column your plan does not include is left out of the rows and named in
withheld, with the plan that includes it. - A page too large for one answer comes back as its first rows with
meta.truncated; narrow the screen or ask for fewer columns.
Limits and quota
- Reads only: it changes nothing.
- Each call spends one Screener run, not an MCP request.
- Screens events dated today or later, and past events too with
include_past. Parking passes and other non-admission items are never included. - Ranking a broad screen by an uncommon column can time out. Narrow the predicate first.