TickerDocs
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_events to find it by name, venue or date, and get_event_analytics for all of its numbers.

Inputs

  • predicate (object, default {}): The conditions, as a predicate: each one names a column, an operator and a value, joined with all (and) or any (or). Leave it out to screen every upcoming event.
  • preset (string): Run a preset screen by its key, like top_selling_24h, as list_screen_columns with view presets gives it: the same rows, in the same order, as the app's preset. Send it instead of predicate and sort.
  • view_id (uuid): Run a saved View by its id, as list_views gives it: the events the app shows for that View now, with the View's own floor setting. Send it instead of predicate and preset. sort, columns and paging still apply.
  • sort (object): The column to rank by, and asc or desc, as { "col": "ea.median_price_pct_7d", "dir": "desc" }.
  • columns (array of strings): The columns each row carries, spelled as list_screen_columns gives them. Leave it out for a short default set.
  • group_by (string): Count the matching events instead of listing them: by performer, venue, or performer_venue (one act at one venue). The largest groups come first. limit and page count groups; sort and columns do not apply. One of performer, venue, performer_venue.
  • min_events (integer): With group_by, leave out groups with fewer events than this. 2 keeps only repeats. Leave it out for 1.
  • page (integer, default 1): The page of results.
  • limit (integer, default 50): Rows per page.
  • count (boolean, default false): 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, default true): Only events Ticker is tracking now. Set false to include inactive events too; their numbers stopped updating.
  • apply_floor (boolean, default true): Leave out thin events, with few listings or a low median price. Set false to screen every event.
  • parking (string, default hide): Parking passes sold as their own event: hide (the default) leaves them out, only returns parking alone, include returns parking beside every other event. With view_id, the View's own choice runs. One of hide, include, only.
  • include_past (boolean, default false): Set true to screen events that have already taken place as well. false when you leave it out. Past events are on the Max plan and above; on another plan true is refused.
  • exclude_stale (boolean, default true): Leave out events whose prices are more than three days old.
  • diagnostics (boolean or on_empty, default on_empty): Explain an empty result: how many events each condition kept. on_empty explains only an empty page, true explains every page, false never. 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_url and the columns you asked for. Pass event_id to any other tool.
  • total and totalPages when count is true.
  • 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 with event_url. At most 100,000 events are grouped, the soonest first, and events_capped says when that cut applied.
  • A diagnostics block 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.

On this page