MCOMP Public API
Ticket market data and organization data, keyed per organization.
Quickstart
1 · Create a key
An owner or admin of your organization goes to Settings > Organization > API Keys on the web, or Settings > API Keys in the desktop app. Give the key a name, choose its scopes and create it. The first key of an organization asks you to accept the MCOMP API Terms of Use on its behalf.
Copy the key when it appears: it is shown once and cannot be displayed again. If the page says the public API is not enabled for your organization, ask for access at [email protected].
2 · Check the key
export MCOMP_API_KEY='mcomp_live_...' # the key you copied from Settings > API Keys
curl -sS https://public-api.mcomp.app/v1/_auth/whoami \
-H "Authorization: Bearer $MCOMP_API_KEY"A working key answers 200 with your organization id, the key prefix and the key's scopes, and costs no points. For example:
{
"org_id": "6f1c2a9e-3b7d-4e2a-9c51-0d8b7e4f2a13",
"key_prefix": "Ab3dE5fG7hJ9",
"scopes": [
"events:search",
"events:read",
"restocks:history:read"
]
}Authorization: Bearer mcomp_live_..., with one space after Bearer. Any other shape (no header, another scheme, two spaces) is blocked before it reaches the API and gets a Cloudflare 403 HTML page instead of a JSON error.Authentication and access
Send the key in the Authorization: Bearer <key> header. Live keys look like mcomp_live_... and
sandbox keys like mcomp_test_...; each environment accepts only its own keys. Keys are accepted
in the header only: a query parameter named apikey, api_key, api-key, key, token,
access_token or secret (any letter case, even with an empty value) is rejected with
400 key_in_url, whatever the route. No CORS headers are served at all, so browsers cannot call the API directly: call
it from a server.
Every authentication failure of a key (unknown, wrong secret, revoked, expired, wrong environment)
is the same 401 invalid_api_key, so a caller learns nothing about why a key failed.
- Server-side only. The API serves no CORS headers, so a browser page cannot call it, and a key in front-end code or a mobile app is a leaked key. Keep keys in your server's secret store or environment.
- One key per integration. An owner or admin can revoke any key in Settings > API Keys without affecting the others. Revoke a key at once if it may have leaked.
- Live and test keys. Live keys start with
mcomp_live_. The sandbox formcomp_test_keys (https://public-api-sandbox.mcomp.app/v1) is not live yet; use a live key during the alpha.
Scopes
A key carries the scopes chosen when it was created, from those enabled for your organization. Each route names the scope it needs:
Event details versus market data
Scopes events:read and events:search cover every event on the platform, whatever the
organization watches. Market data (restocks, primary, secondary, availability, /stock,
/changes) follows the organization's market access setting: with watchlist access only events
on the organization's watchlists are readable (anything else is 403 event_not_in_watchlist), with
all every event is. The watchlists that grant market access are the regular restock watchlist, the
analysis watchlist, TM Queue and Concert Week. GET /v1/watchlists/restocks lists the regular
restock watchlist only; TM Queue and Concert Week events are not listed there although they grant
market access.
An unknown event is always 404 not_found, never 403.
The full contract is an OpenAPI 3.1.0 document: /developers/openapi.yaml.
Limits and client behavior
Limits are per organization, summed across all of its keys.
- Requests: 10 per second with a burst of 30 (defaults; an organization may have its own).
Over the limit:
429 rate_limitedwithRetry-After. Every limited response carriesRateLimit-Limit,RateLimit-RemainingandRateLimit-Reset. - Data budget: 100 points per minute with a burst of 200 (defaults). Each route states its cost
in
x-points. Over the budget:429 budget_exhaustedwithRetry-After. Bulk routes (/events?ids=, /stock, /changes, search) return as much as the budget pays for and report the rest per item.X-MCOMP-Budget-Limit,X-MCOMP-Budget-RemainingandX-MCOMP-Points-Chargedare set on the responses of data routes, including their validation, lookup and limit errors. They are not set on401, on429 rate_limited, on403s from the organization checks or from a single-route scope check, or on /_auth/whoami. The scope403s of /stock and /changes do carry them. - Per-event floor: the same resource of the same event can be requested once per 5 seconds per
organization (resources are the route names, for example
restocksandrestocks_historyhave separate floors; /stock has one resource,stock). Faster requests get429 too_frequentwithRetry-After. Conditional requests (If-None-Match) count against the floor. On the bulk routes (/events?ids=, /stock) the floor is taken per ID before the budget is charged, so an ID that is then reported asbudget_exhaustedhas still used its floor slot. When the budget pays for nothing at all, the whole request is429 budget_exhausted. A request that would have to load uncached data is refused with429 budget_exhaustedwhen the budget is empty, before the load: this includes otherwise-free cold search pages,?ids=and conditional requests on cold keys. Cached answers and304s are never refused by this check (a cached answer is still charged). - /changes has its own limits, described on the route.
- Per-organization floors: /m3-picks and the
/analytics/...rollups are not per event; each can be called once per 5 seconds per organization (x-org-flooron the route). - Bounded heavy reads: listings, seat history and trends (the
market_heavygroup) are always bounded by one event and a window. Section trends take onesection_idand zone trends onezoneper call. Seat history is per seat (/seats/{place_id}/history) or per section over at most 3 days (/seats/history?section=), never a whole event. Each route states its window caps.
Points
| Route kind | Points |
|---|---|
Current state of one event (restocks, primary, secondary, secondary/sections) | 1 |
Zones of one event (primary/zones) | 5 |
History of one event (restocks/history, primary/history, secondary/history) | 5 |
| /events/{id} | 1 |
/events?ids= | 1 per event returned (ok) |
| /events/search | 1 per result returned |
| /stock | 1 per event returned, however many fields it carries |
| /changes | 1 per change returned |
Availability of one event (availability), a map or filter options | 1 |
| Availability history, trends, seat history, restock activity | 5 |
| Listings | 1 per 50 listings returned, rounded up (at least 1) |
Insights (insights, insights/sections, insights/section-scores) | 2 |
| /m3-picks | 2 per pick returned |
| /analytics/secondary-summary | 1 |
A 304 Not Modified answer | 0 |
Organization routes (/org, /watchlists/...), /_auth/whoami | 0 |
The request limit still applies to the zero-cost routes.
How a well-behaved client works
- On any
429or503, wait the whole seconds inRetry-Afterbefore retrying. Do not retry faster, and do not retry other 4xx errors unchanged. - Branch on the error
code:rate_limitedmeans slow down overall,budget_exhaustedmeans your points are spent, andtoo_frequentmeans you asked for the same resource of the same event within 5 seconds (or polled /changes too fast). - /events/{id} and /events?ids= share the
eventfloor, so alternating between them does not get around it. Every other per-event route has a floor of its own. - Watch
RateLimit-RemainingandX-MCOMP-Budget-Remainingto pace yourself before you hit a limit.X-MCOMP-Points-Chargedshows what each call cost. - On /events?ids= and /stock a
200can be a partial answer. Read each item'sstatusand ask again only for items markedtoo_frequent(after theirretry_after) orbudget_exhausted(after the 5-second floor: the item already used its floor slot). - Search and /changes cut the page when the budget runs short: continue from
next_cursorornext(on/changes,has_moretells you more is waiting). A cut search page has noETagand is never answered with304. - Send
If-None-Matchwith the lastETagon single-event routes: an unchanged answer is a304that costs no points (it still counts against the floor). - Send
Accept-Encoding: gzip(most HTTP clients do by default). Responses are compressed only when you ask (see caching below), and bulk answers are the large ones. - Prefer one bulk call over many single-event calls, and the change feed over polling every event.
Caching and conditional requests
Responses that are shared between organizations carry a strong ETag and
Cache-Control: private, max-age=<ttl>. Send If-None-Match to get a 304 with no body (costing 0
points). Server-side freshness: restock and availability current state 5 s, primary and secondary
current state 60 s, history, trends, listings, seat history and insights 60 s, event details
5 minutes, maps and filter options 1 hour. The /analytics/... rollups are the organization's own,
cached 60 s for that organization only (per server) and never shared. Bodies over 1 KiB are gzip-compressed when
the request has Accept-Encoding: gzip.
Recommended integration
- Decide which events to follow: for example the events on your restock watchlist (/watchlists/restocks) or your own list of event ids.
- Take a starting cursor: /changes without
sinceis free and returns the current end of the feed asnext. - Read the current state once with /stock, up to 100 ids per call.
- Poll
/changes?since=<next>every few seconds (at most once per 1 second, one call in flight), keep the changes for your events, re-read those events with/stock, and store the newnext. Whenhas_moreis true, poll again as soon as the poll limit allows. - On
410 cursor_expired, take a fresh cursor first, then re-read everything with/stockand carry on. Taking the cursor before the resync means no change is missed.
The sample accepts event UUIDs or platform:external_id ids. The change feed reports event UUIDs, so it learns each event's UUID from its first /stock answer.
import os, random, time
import requests
BASE = "https://public-api.mcomp.app/v1"
BULK_IDS = 100 # /stock accepts at most this many distinct ids
FLOOR = 5 # seconds between reads of the same event
POLL_LIMIT = 1 # /changes?since= allows 1 call per this many seconds
POLL_EVERY = 3 # comfortably above the poll limit
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['MCOMP_API_KEY']}"
def get(path, **params):
"""GET that waits out Retry-After (plus jitter) on 429 and 503."""
while True:
response = session.get(BASE + path, params=params, timeout=30)
if response.status_code not in (429, 503):
return response
time.sleep(int(response.headers.get("Retry-After", "1")) + random.random())
class Mirror:
"""Local copy of the current state of the events you follow."""
def __init__(self, event_ids, store):
self.event_ids = set(event_ids) # UUIDs or platform:external_id
self.store = store
self.uuids = set() # what /changes reports, learned from /stock
self.not_before = {} # id -> earliest time to ask for it again
def read(self, ids):
"""Bulk-read the ids that are due; partial answers are retried later."""
now = time.monotonic()
due = sorted(i for i in ids if self.not_before.get(i, 0) <= now)
for start in range(0, len(due), BULK_IDS):
response = get("/stock", ids=",".join(due[start:start + BULK_IDS]))
response.raise_for_status()
for item in response.json()["items"]:
if item.get("event_id"):
self.uuids.add(item["event_id"])
if item["status"] == "ok":
self.not_before.pop(item["id"], None)
self.store(item) # restock, primary, secondary, availability
elif item["status"] in ("too_frequent", "budget_exhausted"):
# Both used this event's floor slot: wait before asking again.
wait = item.get("retry_after", FLOOR)
self.not_before[item["id"]] = time.monotonic() + wait
else: # not_found, event_not_in_watchlist, invalid_id
self.not_before.pop(item["id"], None)
def read_all(self):
self.read(self.event_ids)
def read_changed(self, changes):
changed = {c["event_id"] for c in changes} & self.uuids
self.read(changed | set(self.not_before))
def fresh_cursor():
response = get("/changes") # no since: free, returns the current end
response.raise_for_status()
return response.json()["next"]
def run(event_ids, store):
mirror = Mirror(event_ids, store)
cursor = fresh_cursor() # take the cursor first ...
mirror.read_all() # ... then read the current state
while True:
response = get("/changes", since=cursor)
if response.status_code == 410: # cursor_expired: resync
cursor = fresh_cursor()
mirror.read_all()
time.sleep(POLL_LIMIT)
continue
response.raise_for_status()
body = response.json()
mirror.read_changed(body["changes"])
cursor = body["next"]
time.sleep(POLL_LIMIT if body["has_more"] else POLL_EVERY)
/changes call costs 1 point per change returned and nothing when nothing changed, and one /stock call reads up to 100 events. Polling every event on a timer spends your budget on answers that have not changed./changes charges for every change it returns, including changes to events you then ignore. If your organization can read every event, the feed covers the whole platform: watch X-MCOMP-Budget-Remaining and keep enough budget for your /stock reads.Your organization's notifications
/feed returns the notifications your Feed showed in the last 24 hours: restocks, price changes, Smart Alerts, Event Drops, TM Queue and Shopify restocks, newest first. Like every organization read it costs 0 points. Page with next until it is null, then poll again later and stop at the newest notification you already hold. A notification older than 24 hours is gone, so poll at least daily. Presale and access codes are never included.
Errors
Every error uses one envelope and a stable, snake_case code; branch on code, not on the
message. The message is fixed friendly text and may change. Every response carries an
X-Request-Id header, repeated in the envelope as request_id; quote it when you contact support.
Retry-After (whole seconds) is set on 429 and 503. Errors are never cacheable
(Cache-Control: no-store). details is present only when the code has details and is omitted
otherwise. A path that does not exist is 404 not_found and a method other than GET on a known
path is 405 method_not_allowed, both in the same envelope (they are not repeated on every
operation below).
{"error": {"code": "too_frequent", "message": "This resource was requested too recently. Wait a few seconds and retry.",
"request_id": "5c9a2f0e-..."}}
Authorization header is missing or not shaped exactly Bearer mcomp_... is stopped at the network edge with a Cloudflare 403 HTML page, not this envelope. Treat a non-JSON 403 as "fix the header".Error codes
| Code | HTTP | Meaning | What to do | Retry |
|---|---|---|---|---|
| invalid_cursor | 400 | The cursor is not one this route issued. | Send back exactly the cursor the same route returned. | no |
| invalid_days | 400 | days is out of range. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_fields | 400 | fields names an unknown or repeated field. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_filter_rule | 400 | A filter rule is unknown (details.rule) or not valid for the event's platform. | Use only the FilterRules keys with values valid for the platform. | no |
| invalid_granularity | 400 | granularity is not allowed on this route. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_id | 400 | The event identifier is not valid. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_idempotency_key | 400 | The Idempotency-Key is empty, too long or not printable ASCII. | Use 1 to 255 printable ASCII characters. | no |
| invalid_ids | 400 | ids is missing, empty, all invalid, or over the cap. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_platform | 400 | platform is not a known platform. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_query | 400 | A query parameter is invalid. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_range | 400 | range is not an allowed value. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_request | 400 | The body is not one JSON object of the documented members, or a member is missing or out of range (details.field when known). | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_seat | 400 | The place_id is not a valid Ticketmaster seat id. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_section | 400 | section_id (or section) is malformed. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_webhook | 400 | The webhook body is malformed, has an unknown field or is empty. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_webhook_destination | 400 | The URL is not public HTTPS on port 443, or its name resolves to a non-public address. | Use a public HTTPS endpoint without credentials, a fragment or a custom port. | no |
| invalid_webhook_event_types | 400 | No event type, or one that does not exist (details.allowed). | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_webhook_filter | 400 | A folder is not one of your organization's, an id is not a UUID, or a filter is too long. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_window | 400 | window is not an allowed value. | Fix the request; sending it again unchanged gives the same error. | no |
| key_in_url | 400 | A key-like query parameter was sent. | Send the key only in the Authorization header. Treat a key that was put in a URL as exposed and rotate it. | no |
| section_required | 400 | This route needs section_id (or section): one section per call. | Fix the request; sending it again unchanged gives the same error. | no |
| zone_required | 400 | Zone trends need one zone per call. | Fix the request; sending it again unchanged gives the same error. | no |
| invalid_api_key | 401 | The key is unknown, revoked, expired, malformed or for the other environment. (A missing or misshapen header is stopped earlier with an HTML 403.) | Check the key. Do not retry in a loop. | no |
| edge_origin_required | 403 | The request did not arrive through the public API hostname. | Call the API only at its published base URL. | no |
| event_not_in_watchlist | 403 | Your organization's market access does not cover this event. | Add the event to one of your watchlists in MCOMP, or skip it. | no |
| forbidden | 403 | The write points at something the key cannot use, such as another organization's alert destination. | Use your organization's own ids. | no |
| insufficient_scope | 403 | The key lacks a scope this route needs (named in details). | Have an owner or admin create a key with that scope. | no |
| key_creator_not_authorized | 403 | The member who created this key can no longer manage API keys. | Have a current owner or admin create a new key, and revoke the old one. | no |
| module_disabled | 403 | This restock module is off for your organization. | Turn it on in MCOMP, or skip the event. | no |
| org_api_suspended | 403 | API access for your organization is suspended. | Contact [email protected]. | no |
| org_inactive | 403 | Your organization is not active. | Contact [email protected]. | no |
| org_paused | 403 | Your organization is paused. | Contact [email protected]. | no |
| plan_capability_required | 403 | Your organization's plan does not include this capability (named in details). | Contact [email protected]. Ask about your plan. | no |
| provider_disabled | 403 | Shopify restocks are not enabled for your organization. | Contact [email protected]. | no |
| public_api_not_enabled | 403 | The API is not enabled for your organization. | Contact [email protected]. Ask for access. | no |
| subscription_required | 403 | Your organization is on a free trial. The API needs a paid subscription. | Contact [email protected]. Ask about upgrading. | no |
| not_found | 404 | The path, event or folder does not exist, or is not on your list. | Check the identifier. Do not retry. | no |
| method_not_allowed | 405 | This path does not support the method. | Use a method the reference lists for the path. | no |
| already_exists | 409 | The item already exists (for example the event is already on the list, or the folder name is taken). | Treat it as done, or use another name. | no |
| conflict | 409 | A concurrent change conflicted with the write. | Re-read the current state and retry. | with backoff |
| idempotency_in_progress | 409 | The first request with this Idempotency-Key is still running. | Wait Retry-After and retry the same request with the same key: you get its answer. | after Retry-After |
| limit_reached | 409 | Your organization's cap for this item is full (details.limit, details.current, details.requested). | Remove items you no longer need, or ask for a higher limit. | no |
| tracking_paused | 409 | Tracking is paused for this Shopify product. | Try again later or watch another product. | no |
| webhook_delivery_not_redeliverable | 409 | The delivery is still pending, or 20 manual deliveries are already waiting. | Wait for the pending deliveries to finish. | with backoff |
| webhook_inactive | 409 | The webhook is switched off. | Switch it on (PATCH active: true), then retry. | no |
| webhook_limit_reached | 409 | Your organization has its maximum number of webhooks. | Delete a webhook you no longer use. | no |
| cursor_expired | 410 | The /changes cursor is older than the oldest retained change. | Call /changes without since for a fresh cursor, re-read current state with /stock, then keep polling. | no |
| precondition_failed | 412 | The configuration changed since your ETag. | Re-read the current ETag (it is in the ETag header and details.current_etag), check your change still applies, and retry with it. | no |
| payload_too_large | 413 | The body is over 256 KiB. | Split the request (bulk routes take up to 200 events). | no |
| unsupported_media_type | 415 | The body was not sent as JSON. | Send Content-Type: application/json. | no |
| event_not_eligible | 422 | The event cannot be added (past, cancelled or on an unsupported platform). | Skip the event. | no |
| idempotency_key_reused | 422 | This Idempotency-Key was already used with a different request. | Use a new key for a new request; reuse a key only to retry the identical request. | no |
| precondition_required | 428 | This write needs If-Match. | Send the configuration's ETag (from the last write or GET .../config-version) as If-Match. | no |
| budget_exhausted | 429 | The data budget (points) is spent. | Wait Retry-After. On bulk routes, retry only the items reported as budget_exhausted. | after Retry-After |
| rate_limited | 429 | The request rate limit was hit. | Wait Retry-After and spread requests out. RateLimit-* headers show the bucket. | after Retry-After |
| resolve_rate_limited | 429 | The resolve bucket is empty: yours (30 calls a minute), or the service-wide provider budget (details.scope is global). | Wait Retry-After. Inputs that are MCOMP event ids or platform:external_id MCOMP already has never use the shared budget. | after Retry-After |
| too_frequent | 429 | The same resource of the same event was requested too soon, or /changes was polled too fast. | Wait Retry-After (or the item retry_after on bulk routes) before asking for it again. | after Retry-After |
| write_rate_limited | 429 | Your organization's writes bucket (or the app's own write limit for this action) is empty. | Wait Retry-After, then send the write again with the same Idempotency-Key. | after Retry-After |
| internal_error | 500 | Something failed on our side. | Retry with backoff. If it persists, contact [email protected] with the request_id. | with backoff |
| upstream_unavailable | 502 | The event provider could not be reached. | Retry later with backoff. | with backoff |
| service_unavailable | 503 | A dependency is slow or down, or a search term was too broad. | Wait Retry-After. For search, use a more specific term. | after Retry-After |
| temporarily_disabled | 503 | This part of the API is switched off for now. | Wait Retry-After and back off. | after Retry-After |
| webhook_secrets_unavailable | 503 | Signing keys cannot be created right now. | Retry shortly. Contact [email protected]. | with backoff |
Conventions
Times, money and nullability
All times are RFC 3339 in UTC. Money is a decimal string with two fraction digits (for example
"40.50"), never a number. Fields that can be unknown are null rather than omitted, except where
a field is marked optional (history points omit values that are unknown).
Currency. Primary and secondary prices carry an ISO currency next to them. Restock prices have
no currency field: they are in the listing currency of the platform they came from.
Pagination cursors
Cursors (cursor, next, next_cursor) are opaque strings. Do not parse or build them. A cursor
is not bound to the route that issued it, but only the route that issued it can interpret it
meaningfully: always send a cursor back to the same route.
A listings cursor (next_cursor of /events/{id}/listings) is also bound to its event and to the
section_id and platform filters it was issued with, and only the exact text issued is accepted;
anything else is 400 invalid_cursor. Page
through an event by sending each next_cursor back until it is null. The first page has the
5-second per-event floor; the later pages of an event share a floor of one page per second.
Writes
Answers
- Every success is
200with a body. A create or update answers with the object, in the same shape the matching read serves. A delete answers{"id": "...", "deleted": true}. - Bulk actions (up to 200 events) answer one result per event, so one bad event never fails the batch. A
platform:external_idthat matches no event is reported asfailed/not_found. - Each write needs its own write scope (for example
watchlists.restocks:write), which an MCOMP admin grants to your organization. Changes show in the app's Activity as made by the key.
Limits
- Writes cost 0 data points. They use their own writes bucket: 2 per second with a burst of 10 per organization (
X-MCOMP-Writes-Limit,X-MCOMP-Writes-Remaining). Writes also count against the app's own write limits for the same action. Over either:429 write_rate_limitedwithRetry-After. - POST /events/resolve has its own bucket of 30 calls a minute, and inputs sent to a provider share a service-wide budget. An MCOMP event id or a known
platform:external_idis answered from the catalog and uses neither.
Retries: Idempotency-Key
Send Idempotency-Key (1 to 255 printable ASCII characters) on any write you might retry. For 24 hours, the same key with the same request replays the first answer with Idempotent-Replayed: true and writes nothing. Keys are per API key. The same key with a different request is 422 idempotency_key_reused; while the first request still runs, a retry gets 409 idempotency_in_progress. Rate limits, server errors and 412/428 are not kept, so a retry with the same key runs again.
Conditional writes: If-Match
A watchlisted event's restock configuration (its filters, delivery settings and channels) has a version. Every write that changes it returns the new version in ETag; config-version reads it. Filter update, delete and reorder, delivery and channel writes need If-Match with it (428 without; 412 precondition_failed with the current version when stale; * matches any). Send the ETag as you received it: our proxy may deliver it in weak form, W/"…", which matches the same version. Shopify watch updates take the watch's own version the same way, from its etag field or the ETag of a previous write.
# 1. Read the configuration version of a watchlisted event.
curl -sS https://public-api.mcomp.app/v1/watchlists/restocks/events/$EVENT/config-version \
-H "Authorization: Bearer $MCOMP_API_KEY"
# ETag: "9f2c..."
# 2. Change a filter with it. Retry with the same Idempotency-Key if the
# connection drops: you get the first answer back, not a second write.
curl -sS -X PATCH https://public-api.mcomp.app/v1/watchlists/restocks/events/$EVENT/filters/$FILTER \
-H "Authorization: Bearer $MCOMP_API_KEY" \
-H "Content-Type: application/json" \
-H 'If-Match: "9f2c..."' \
-H "Idempotency-Key: filter-$FILTER-2026-11-18-1" \
-d '{"is_active": false}'Webhooks
Set up
- Create a webhook in the app (Settings > Organization > Webhooks) or with POST /webhooks (scopes
webhooks:manageandfeed:read, since a webhook sends your feed). Pick the event types:restock,price_change,smart_alert,event_drop,queue,shopify. Optionally narrow it to some restock folders or events. - The answer shows the webhook's
signing_key(whsec_...) once. Store it as a secret on your server. Lost it? Rotate it with rotate-signing-key. - MCOMP sends a
pingright away. Check the delivery log to see it arrive; send another with ping. - Your endpoint must be public HTTPS on port 443. Private, loopback and link-local addresses are refused, when you save the URL and again at every delivery.
What a delivery looks like
A POST with a JSON body of at most 256 KiB. data is the notification exactly as /feed returns it (presale and access codes are never included). In the rare case a notification is larger, the body says "truncated": true and carries only its id: read the rest from /feed.
POST /mcomp-webhook HTTP/1.1
Content-Type: application/json
User-Agent: MCOMP-Webhooks/1
X-MCOMP-Event: restock
X-MCOMP-Delivery: 3f0c9a6e-6c1b-4f7e-9a51-2b8e7d4c1a90
X-MCOMP-Signature-256: sha256=9c1e...
{"type":"restock","webhook_id":"7d2f...","created_at":"2026-11-18T15:04:05.123Z",
"data":{"id":"b81c...","type":"restock","kind":"restock_alert","event":{"name":"..."}, ...}}Verifying signatures
X-MCOMP-Signature-256 is sha256= followed by the hex HMAC-SHA256 of the raw body bytes, keyed with the whole signing key (including whsec_). Compute it over the bytes you received, before parsing the JSON, and compare in constant time. Reject anything that does not match.
import hashlib
import hmac
import os
from flask import Flask, abort, request
app = Flask(__name__)
SIGNING_KEY = os.environ["MCOMP_WEBHOOK_SIGNING_KEY"] # whsec_..., shown once when you create the webhook
def verify(signing_key: str, body: bytes, header: str | None) -> bool:
expected = "sha256=" + hmac.new(signing_key.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header or "")
@app.post("/mcomp-webhook")
def mcomp_webhook():
body = request.get_data() # the raw bytes, before any JSON parsing
if not verify(SIGNING_KEY, body, request.headers.get("X-MCOMP-Signature-256")):
abort(401)
delivery_id = request.headers["X-MCOMP-Delivery"] # the same on every retry: de-duplicate on it
event = request.get_json()
# Queue the work and answer fast: anything slower than 10 seconds counts as a failure.
print(delivery_id, event["type"])
return "", 204
import crypto from 'node:crypto'
import express from 'express'
const SIGNING_KEY = process.env.MCOMP_WEBHOOK_SIGNING_KEY // whsec_..., shown once when you create the webhook
export function verify(signingKey, rawBody, header) {
const expected = Buffer.from('sha256=' + crypto.createHmac('sha256', signingKey).update(rawBody).digest('hex'))
const given = Buffer.from(header ?? '')
return expected.length === given.length && crypto.timingSafeEqual(expected, given)
}
const app = express()
// express.raw keeps the exact bytes; verify before parsing JSON.
app.post('/mcomp-webhook', express.raw({ type: 'application/json' }), (req, res) => {
if (!verify(SIGNING_KEY, req.body, req.get('X-MCOMP-Signature-256'))) return res.sendStatus(401)
const deliveryId = req.get('X-MCOMP-Delivery') // the same on every retry: de-duplicate on it
const event = JSON.parse(req.body.toString('utf8'))
// Queue the work and answer fast: anything slower than 10 seconds counts as a failure.
console.log(deliveryId, event.type)
res.sendStatus(204)
})
app.listen(3000)
whsec_test and the body {"type":"ping"}, your verifier must expect sha256=327470f0f524b54cba99ad6ae59d5d3070e9a35365a04aa8bb2d01d08ee66421.Retries, ordering and switch-off
- Any 2xx answer within 10 seconds is a success. Redirects are not followed. Answer fast and do the work later.
- A failed attempt is retried after about 1 minute, 5 minutes, 30 minutes, 2 hours, 6 hours and 12 hours (with jitter), then the delivery is marked failed. You can redeliver it from the log.
- Delivery is at least once: a retry, or a redelivery you ask for, can repeat a notification. De-duplicate on
X-MCOMP-Delivery(the same on every retry) or ondata.id(the same on a redelivery). Deliveries are roughly in order, not strictly. - When every attempt has failed for 3 days, the webhook is switched off (
disabled_reason: failing) and your owners and admins get an app notification. Fix the endpoint, then switch it back on; notifications from while it was off are not replayed. - Nothing is delivered while the API is disabled or suspended for your organization, while your organization is not allowed both
webhooks:manageandfeed:read, during a free trial, or when the user who created the webhook is no longer an owner or admin.
Endpoint reference
Event details and search. Cover every event on the platform.
GET/v1/events/searchSearch events
Searches events by name or artist. Cursor-paginated, ordered by event date then id.
qand/orartistare required, and each one you send needs at least 3 letters or digits (punctuation and spaces do not count).venue,city,fromandtoonly narrow the result; a search by venue or city alone is not possible (useq).fromdefaults to the start of the previous UTC day, so by default only upcoming events are returned. If you settoearlier than that default, you are asking for the past on purpose andfromis left open.- Very broad terms may time out and answer
503 service_unavailable; retry with a more specific term. - Costs 1 point per result returned. If the budget pays for fewer results than the page holds,
the page is cut and
next_cursorresumes right after the last result returned. A page with no results, or a304, costs 0. - Pages are cached for 60 seconds.
Needs scope events:search, which covers every event regardless of the watchlist.
Parameters
q query | string | Text matched against event names and artist names. At least 3 letters or digits. max length 100 |
artist query | string | Text matched against artist names. At least 3 letters or digits. max length 100 |
venue query | string | Narrows by venue name. Cannot be the only search term. max length 100 |
city query | string | Narrows by venue city. Cannot be the only search term. max length 100 |
from query | DateOrDateTime | Earliest event date, RFC 3339 or YYYY-MM-DD (UTC). Defaults to the start of yesterday (UTC). |
to query | DateOrDateTime | Latest event date, inclusive, RFC 3339 or YYYY-MM-DD (UTC; a bare date covers the whole day). |
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next_cursor of the previous page. Opaque.max length 256 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}Get one event
Event details: name, date, venue, artists, the platforms the event is listed on and, when known, Ticketmaster details. Presale and access codes are never part of the response.
Needs scope events:read, which covers every event regardless of the watchlist. Costs 1 point
(0 for a 304). Subject to the per-event floor (resource event, 5 s, conditional requests
count). Cached 5 minutes.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/eventsGet up to 100 events
Event details for up to 100 event identifiers in one call, answered per identifier in request
order. The HTTP status is 200 unless the whole request is rejected; read each item's status.
- The whole request is
400 invalid_ids(withdetails.max= 100) whenidsis missing or empty, when none of the entries is a valid identifier, or when it has more than 100 distinct entries. - Statuses:
ok,not_found,invalid_id,too_frequent(withretry_afterseconds) andbudget_exhausted. - Two identifiers naming the same event are served and charged once.
- Costs 1 point per
okevent. The per-event floor (resourceevent, 5 s) is taken per event before the budget, so an event reported asbudget_exhaustedhas still used its floor slot. When the budget pays for nothing the whole request is429 budget_exhausted. - The response is never answered with
304(points are charged).
Needs scope events:read, which covers every event regardless of the watchlist.
Parameters
ids query · required | string | Comma-separated event identifiers (UUID or platform:external_id), at most 100 distinct. |
Responses
Per-event restocks, primary, secondary and bulk stock. Follow the organization's market access.
GET/v1/events/{id}/restocksCurrent restock state
The current restock state of an event on every platform it has data for. An event with no
restock data has an empty platforms list.
Restock prices have no currency field: they are in the listing currency of the platform
they came from (the restock data does not store one).
last_restocked_at is the time of the last restock observed since tracking began, and is null
when no restock has been observed yet. null means "not observed", not "never restocked". It
is filled in as each event is restocked; there is no backfill of older restocks.
Needs scope restocks:history:read and market access to the event. Costs 1 point (0 for a
304). Per-event floor: resource restocks, 5 s. Cached 5 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/restocks/historyRestock history
The restock series of one platform over a window. Windows 3d and 1w are intraday, 1m is
mixed, 6m and all are daily. Daily points carry that day's close and are stamped at
midnight of the day in America/New_York (as RFC 3339 UTC). A series is capped at 4000 points
(the newest ones, truncated: true).
Restock prices have no currency field (see getRestocks).
Needs scope restocks:history:read and market access to the event. Costs 5 points (0 for a
304). Per-event floor: resource restocks_history, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
window query | string | Time window. one of 3d, 1w, 1m, 6m, all · default 1w |
platform query | PlatformName | Platform to read. Defaults to the event's primary platform (Ticketmaster when it has one). |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/primaryCurrent primary-market state
The current primary-market state of an event on every platform it has data for (empty
platforms when there is none). Prices are decimal strings in currency.
Needs scope primary:read and market access to the event. Costs 1 point (0 for a 304).
Per-event floor: resource primary, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/primary/historyPrimary-market history
The primary-market series of one platform. Ranges 24h to 30d are intraday buckets; 6m and
all are daily buckets whose bucket_start is midnight UTC of the day. Prices are decimal
strings in currency. A series is capped at 4000 points (the newest ones, truncated: true).
Needs scope primary:read and market access to the event. Costs 5 points (0 for a 304).
Per-event floor: resource primary_history, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
range query | string | Time range. one of 24h, 3d, 7d, 30d, 6m, all · default 7d |
platform query | PlatformName | Platform to read. Defaults to the event's primary platform (Ticketmaster when it has one). |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/primary/zonesCurrent primary-market state by zone
The current state of each zone of one platform. Zone data is cached 60 seconds and, unlike the
event-level state, is not refreshed early when the event changes. A zone the platform no longer
lists is returned with status_label previously_observed_unavailable only if it was seen in
the last 30 days, and the 24-hour change fields compare against a point 24 to 48 hours before
the zone's capture (null when there is none).
Needs scope primary:read and market access to the event. Costs 5 points (0 for a 304).
Per-event floor: resource primary_zones, 5 s.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
platform query | PlatformName | Platform to read. Defaults to the event's primary platform (Ticketmaster when it has one). |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/secondaryCurrent secondary-market state
The current secondary-market (resale) state of an event (Vivid Seats; empty platforms when
there is none). Prices are decimal strings in currency. The *_all_in prices include fees.
Needs scope secondary:read and market access to the event. Costs 1 point (0 for a 304).
Per-event floor: resource secondary, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/secondary/sectionsCurrent secondary-market state by section
The current secondary-market state of each section. section_key is the stable section
identifier; section_id is null for a section that has no internal id yet. Cached 60 seconds and,
unlike the event-level state, not refreshed early when the event changes.
Needs scope secondary:read and market access to the event. Costs 1 point (0 for a 304).
Per-event floor: resource secondary_sections, 5 s.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/secondary/historySecondary-market history of one metric
One metric over the last days days, for the whole event or one section. Windows up to 30 days
are intraday; longer windows use daily buckets whose bucket_start is midnight UTC of the day. A
series is capped at 4000 points (the newest ones, truncated: true). Price metrics are decimal
strings with a currency; count metrics are numbers and have a null currency.
Needs scope secondary:read and market access to the event. Costs 5 points (0 for a 304).
Per-event floor: resource secondary_history, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
metric query · required | string | The metric to return. one of stock_count, listed_count, get_in_price, avg_listing_price, min_listing_price, max_listing_price |
scope query | string | Whole event, or one section (then section_id is required).one of event, section · default event |
section_id query | string (uuid) | A section_id from getSecondarySections. Required when scope=section, not allowed otherwise. |
days query | integer | How many days back. default 30 · 1 to 365 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/availabilityCurrent availability, event and sections
The current inventory availability of the event (event, null when none is known) and of each
section (at most 1000 sections, ordered by name; truncated: true when there are more).
source is reported (the platform reported the count) or derived (MCOMP derived it).
Needs scope availability:read and market access to the event. Costs 1 point (0 for a 304).
Per-event floor: resource availability, 5 s. Cached 5 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/availability/historyAvailability history, event or one section
The availability series of the event, or of one section with section_id (never every section at
once). Each point is the latest snapshot of its bucket. Windows: hourly up to 14 days; daily,
weekly and monthly up to 180 days (history is kept 180 days). A series is capped at 4000
points (the newest ones, truncated: true).
Needs scope availability:read and market access to the event. Costs 5 points (0 for a 304).
Per-event floor: resource availability_history, 5 s (shared by the event and section series).
Cached 60 seconds. Errors: invalid_granularity, invalid_days (details.max), invalid_section.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
granularity query | string | Bucket size. one of hourly, daily, weekly, monthly · default hourly |
days query | integer | How many days back. At most 14 for hourly, 180 otherwise.default 7 · 1 to 180 |
section_id query | string (uuid) | One section's id (for example from getAvailability). Omit for the whole event. |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/trendsEvent price and listing trend
Listing price range and counts of the event per bucket. Each bucket carries the latest roll-up at or
before it within a freshness window; a bucket with no data has null values. Windows: minutely up to
1 day, hourly up to 14 days, daily, weekly and monthly up to 365 days. A series is capped at
4000 points (the newest ones, truncated: true). Prices are decimal strings.
Needs scope trends:read (the plan must include Analysis) and market access to the event. Costs 5
points (0 for a 304). Per-event floor: resource trends, 5 s. Cached 60 seconds. Part of the
market_heavy group, which can be paused on its own.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
granularity query | string | Bucket size. one of minutely, hourly, daily, weekly, monthly · default hourly |
days query | integer | How many days back. At most 1 for minutely, 14 for hourly, 365 otherwise. Default 1 for minutely, 7 otherwise.1 to 365 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/trends/sectionsPrice and listing trend of one section
The trend of one section (section_id is required: one section per call), one row per bucket and
ticket type. Sections have no minutely roll-up: minutely is served as hourly
(granularity says what was served, requested_granularity what was asked). Windows as in
getEventTrend, using the served granularity.
Needs scope trends:read (the plan must include Analysis) and market access to the event. Costs 5
points (0 for a 304). Per-event floor: resource trends_sections, 5 s. Cached 60 seconds.
Errors: section_required, invalid_section, invalid_granularity, invalid_days.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
section_id query · required | string (uuid) | A section id, for example from getAvailability or getSecondarySections. |
granularity query | string | Bucket size. one of minutely, hourly, daily, weekly, monthly · default hourly |
days query | integer | How many days back. At most 1 for minutely, 14 for hourly, 365 otherwise. Default 1 for minutely, 7 otherwise.1 to 365 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/trends/zonesPrice-point trend of one zone
Quantity and listing counts per price point of one zone (zone, required), per bucket. Zone names
appear on listings (zone). One zone per call, with tighter windows than the other trends:
minutely covers the last 2 hours, hourly up to 7 days, daily up to 90 days, weekly and
monthly up to 365 days. Each bucket has one point per price point of the zone, and a series is
capped at 4000 points (the newest ones, truncated: true), so a zone with many price points
covers less than the whole window at hourly; use daily or fewer days to see it all.
Needs scope trends:read (the plan must include Analysis) and market access to the event. Costs 5
points (0 for a 304). Per-event floor: resource trends_zones, 5 s. Cached 60 seconds.
Errors: zone_required, invalid_query (a bad or repeated zone), invalid_granularity, invalid_days.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
zone query · required | string | The zone name (at most 200 bytes, no control characters). max length 200 |
granularity query | string | Bucket size. one of minutely, hourly, daily, weekly, monthly · default hourly |
days query | integer | How many days back. At most 1 for minutely, 7 for hourly, 90 for daily, 365 otherwise. Default 1 for minutely, 7 otherwise.1 to 365 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/listingsActive listings, by price
The event's active listings, cheapest first (ties by an internal order), cursor-paginated: pass
next_cursor back as cursor until it is null. A cursor is bound to the event and to the
section_id and platform filters it was issued with (invalid_cursor otherwise); limit may
change between pages. Prices are decimal strings in the listing's currency. Listings carry no
platform listing ids or seller notes.
Needs scope listings:read and market access to the event. Costs 1 point per 50 listings
returned, rounded up, and at least 1 (0 for a 304); a 500-listing page costs 10. Per-event
floor: the first page has resource listings, 5 s; the cursor pages of an event share resource
listings_page, one page per second. Cached 60 seconds. Part of the
market_heavy group. Errors: invalid_cursor, invalid_query (limit), invalid_section,
invalid_platform.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
section_id query | string (uuid) | One section's id (for example from getAvailability). Omit for the whole event. |
platform query | PlatformName | Platform to read. Defaults to the event's primary platform (Ticketmaster when it has one). |
limit query | integer | Listings per page. default 100 · 1 to 500 |
cursor query | string | The next_cursor of the previous page. Omit for the first page.max length 512 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/seats/{place_id}/historyHistory of one seat
The listing, removal and price-change history of one Ticketmaster seat, newest first, per lane
(standard primary offer or resale), over the last days days (default 30, at most 90). A
removal listed again within 20 minutes at the same
all-in price shows as one held entry with held_seconds. place_id is the Ticketmaster place
id (base32 of SECTION:ROW:SEAT); entries from getSectionSeatHistory carry it. Prices are
decimal strings. At most limit entries (truncated: true when there are more).
Unlike the MCOMP app, which shows a seat's history only from when the organization started
tracking the event, the API returns the full recorded history, the same for every organization
that may read the event.
Needs scope seats:history:read and market access to the event. Costs 5 points (0 for a 304).
Per-event floor: resource seat_history, 5 s. Cached 60 seconds. Part of the market_heavy
group. Errors: invalid_seat, invalid_days, invalid_query (limit).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
place_id path · required | string | The Ticketmaster place id. max length 200 |
days query | integer | How many days back. default 30 · 1 to 90 |
limit query | integer | Most entries to return. default 100 · 1 to 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/seats/historySeat history of one section
The seat changes of one section (section, the Ticketmaster section label, required) over the
last days days (at most 3), newest first, each with its seat. Never a whole event: one section
per call. Holds are folded per seat as in getSeatHistory. At most limit rows are read
(truncated: true when there were more). Like getSeatHistory, it is not limited to the time
since the organization started tracking the event, unlike the MCOMP app.
Needs scope seats:history:read and market access to the event. Costs 5 points (0 for a 304).
Per-event floor: resource seat_history_section, 5 s. Cached 60 seconds. Part of the
market_heavy group. Errors: section_required, invalid_section, invalid_days,
invalid_query (limit).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
section query · required | string | The section label (at most 100 bytes, no control characters). max length 100 |
days query | integer | How many days back. default 1 · 1 to 3 |
limit query | integer | Most rows to read. default 200 · 1 to 500 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/mapSection map
The normalized section map of the event on a platform, as MCOMP last cached it: svg-sections
(an SVG view_box and section shapes with their section names) or section-bounds (a bounding
box and section boxes). none with a reason when there is no usable map (not_available when
nothing is cached for the platform). The API never fetches a map from the platform on request.
Seat positions are not included.
Needs scope maps:read and market access to the event. Costs 1 point (0 for a 304). Per-event
floor: resource map, 5 s. Cached 1 hour: send If-None-Match with the ETag to revalidate.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
platform query | PlatformName | Platform to read. Defaults to the event's primary platform (Ticketmaster when it has one). |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/filter-optionsFilter options (sections, rows, zones, ticket types)
The sections, rows, zones and ticket types the platform lists for the event, as MCOMP last cached them (sorted, unique; empty lists when nothing is cached). Useful values for listings filters and restock filter rules.
Needs scope maps:read and market access to the event. Costs 1 point (0 for a 304). Per-event
floor: resource filter_options, 5 s. Cached 1 hour, with ETag.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
platform query | PlatformName | Platform to read. Defaults to the event's primary platform (Ticketmaster when it has one). |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/stockCurrent market state of up to 100 events
The current restock, primary, secondary and availability state of up to 100 events in one call.
Each requested field is embedded as the same object the single route returns (for example
restock is {"event_id": ..., "platforms": [...]}), not a bare array. availability is null
for an event that has no availability row.
fieldsis a comma-separated subset ofrestock,primary,secondary,availability. Omitted means every field your key and organization may read. Each field needs its scope:restocks:history:read,primary:read,secondary:read,availability:read. Requesting a field without its scope is403 insufficient_scopefor the whole request. A key with none of the four scopes gets403 insufficient_scopewithdetails.required_scopeslisting all of them.- The whole request is
400 invalid_ids(withdetails.max= 100) whenidsis missing or empty, when none of the entries is a valid identifier, or when it has more than 100 distinct entries. An unknown or repeated field name, or only commas, is400 invalid_fields. - Answered per identifier in request order; HTTP
200unless the whole request is rejected. Statuses:ok,not_found,event_not_in_watchlist,invalid_id,too_frequent(withretry_after) andbudget_exhausted. Field data is present only forok. event_idisnullforinvalid_idandnot_found, and also forevent_not_in_watchlist: a hidden event never reveals its identifier mapping.- Costs 1 point per
okevent however many fields it carries. The per-event floor (resourcestock, 5 s) is taken per event before the budget, so an event reported asbudget_exhaustedhas still used its floor slot. Events that are not found or not visible take no floor slot. When the budget pays for nothing the whole request is429 budget_exhausted. - Never answered with
304; noETag.
Needs at least one of the four field scopes (see above), so x-required-scopes is "any".
Parameters
ids query · required | string | Comma-separated event identifiers (UUID or platform:external_id), at most 100 distinct. |
fields query | string | Comma-separated fields to return. Defaults to every field you may read. e.g. restock,availability |
Responses
MCOMP's proprietary signals (Primary Insights, section market and scores, M3 Picks). Follow the organization's market access.
GET/v1/events/{id}/insightsPrimary Insights of an event
MCOMP's Primary Insights for the event on a platform: freshness, stock and price movement over 4
hours, 24 hours and 7 days, sold-out state, the resale comparison, best sections and section
grades, reason badges and data quality flags. available is false (and the values null) when
there is no primary data for the platform. Prices are decimal strings in currency.
Needs scope insights:read and market access to the event. Costs 2 points (0 for a 304).
Per-event floor: resource insights, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
platform query | PlatformName | Platform to read. Defaults to the event's primary platform (Ticketmaster when it has one). |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/insights/sectionsSection market (primary versus resale)
Each section's primary all-in get-in price against Vivid Seats (stock, listed count, get-in and
average all-in prices), with the all-in spread_all_in, demand and risk tags, and per-zone
rollups. section_key matches getSectionScores and getSecondarySections.
Needs scope insights:read and market access to the event. Costs 2 points (0 for a 304).
Per-event floor: resource insights_sections, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/events/{id}/insights/section-scoresSection scores
MCOMP's score of each section against the resale market: an A, B or C grade, a 0-100 score,
the margin, net resale and target_price, and the reasons and risks behind it. Best score
first.
Needs scope insights:read and market access to the event. Costs 2 points (0 for a 304).
Per-event floor: resource insights_section_scores, 5 s. Cached 60 seconds.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/m3-picksM3 Picks
MCOMP's M3 Picks, best score first: upcoming events ranked by the primary-to-resale opportunity,
with the score, rank bucket, reason badges and risk flags. The list is drawn from the top 500
picks of the bucket; in watchlist market access only the picks in the org's watchlists are
returned, so an org may get fewer than limit, and an event of its own ranked below the top 500
is not listed.
Needs scope insights:read. Costs 2 points per pick returned (0 for a 304, 0 for an empty
list). Per-org floor: one call every 5 s (resource m3_picks, not per event). Cached 60 seconds.
Parameters
bucket query | string | Rank bucket. Omit for elite, strong and viable together. one of elite, strong, viable, borderline |
limit query | integer | Most picks to return. default 50 · 1 to 100 |
Responses
If-None-Match validator still matches. No body, 0 points.Rollups of the organization's own alerts and tracked events.
GET/v1/analytics/restock-activityRestock activity (last 24 hours)
The organization's own restock alerts over the last 24 hours: totals, hourly buckets, the peak hour, and rollups by event, venue and artist (seats counted once per seat).
Needs scope analytics:read. Costs 5 points (0 for a 304). Per-org floor: one call every 5 s
(resource analytics_restock_activity). Cached 60 seconds for the organization only (never shared).
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/analytics/secondary-summaryResale market summary of the organization's events
How the organization's tracked events price on Vivid Seats against primary: how many are above,
strongly above, at or below cost, and a histogram of the spread (buckets, from
bucket_start_percent in steps of bucket_width_percent).
Needs scope analytics:read. Costs 1 point (0 for a 304). Per-org floor: one call every 5 s
(resource analytics_secondary_summary). Cached 60 seconds for the organization only (never shared).
Responses
If-None-Match validator still matches. No body, 0 points.A cheap poll for what changed.
GET/v1/changesWhat changed since a cursor
A cheap poll for "which events changed". Start without since to receive a cursor, then poll with
since=<next> and re-read the changed events (for example with /stock).
- Cursor.
nextis an opaque cursor: the id of the last change returned when the page was cut bylimitor your budget, otherwise the last entry scanned (entries that were not yours to see are skipped, not rescanned). Pass it back assince. A call withoutsincereturns no changes,next= the current end of the feed, 0 points, and is exempt from the poll limits below. - 410
cursor_expired. A cursor older than the oldest retained change (the feed keeps about the most recent 200,000 changes, platform-wide; how long that covers depends on the change rate) is410withdetails.resync = "/v1/stock": re-read the current state with /v1/stock and start again withoutsince. A cursor obtained while the feed was empty (after a first deploy or a restart of the feed store) is deliberately fail-safe: once newer entries exist it may answer410once, and you resync. That costs one extra resync, never a silent gap. - Poll limits. Calls with
sinceare limited to 1 per second per organization, and only one may be in flight at a time. Beyond that:429 too_frequentwithRetry-After. Polling every 2 to 5 seconds is plenty. - Content. At most
limitchanges of the kinds your key's scopes allow (restockneedsrestocks:history:read,availabilityneedsavailability:read,primaryneedsprimary:read,secondaryneedssecondary:read) and for events your organization may read. Repeated changes are collapsed per (event, platform, kind), keeping the latest. Up to 5000 feed entries are examined per call;has_moreis true when more remain, whether because oflimit, your budget or that cap. - No progress without cost, and no cost without progress. If entries were examined and none
concern you, the answer is an empty list with an advanced
nextat 0 points. - Cost. 1 point per change returned. If the budget pays for fewer, the list is cut and
nextresumes after the last one returned; if it pays for none,429 budget_exhausted. nextis global. Because the cursor is a position in a feed shared by all customers, it reveals the platform-wide timestamp of the last entry examined (the id embeds a millisecond time). It never reveals other organizations' data.- Never answered with
304; noETag.
Needs at least one market scope (x-required-scopes is "any"); the scopes you hold decide which
kinds you see.
Parameters
since query | string | The next of a previous response. Omit to get a starting cursor.pattern ^[0-9]+-[0-9]+$ |
limit query | integer | Maximum number of changes returned. default 500 · 1 to 1000 |
Responses
The calling organization's own profile and watchlist configuration. Cost 0 points.
GET/v1/orgThe calling organization
The organization's name, plan, capabilities, limits, API settings (market access, allowed scopes, your effective rate limits) and the calling key's own prefix, name and scopes. No member, creator, email or contact details are ever returned.
Needs scope org:read. Costs 0 points (the request limit applies). Strong ETag, 304 supported,
Cache-Control: private, max-age=30.
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/watchlists/restocksThe restock watchlist
The events on the organization's regular restock watchlist, cursor-paginated and ordered by
event id (stable under concurrent changes, not by time). folders lists every folder of the
organization on every page.
TM Queue and Concert Week lists are not listed here, although events on them still grant market access (see the overview).
Needs scope watchlists.restocks:read. Costs 0 points. Strong ETag, 304 supported,
Cache-Control: private, max-age=0 (always revalidate).
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 64 |
folder_id query | string (uuid) | Only events filed in this folder. Must be a folder of your organization, else 404 not_found. |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/watchlists/restocks/events/{id}/filtersAlert filters of a watchlisted event
The alert filters of an event on the restock watchlist, in evaluation order. An event that is not
on the watchlist, and an unknown event, are the same 404 not_found. A watchlisted event with no
filters returns [].
rules is not a passthrough: only a fixed allowlist of seat, row, zone, price and quantity
keys is re-serialized and everything else is dropped. When a known key was dropped (wrong type or
over the size caps of 5000 list items and 500 characters per string) the filter carries
rules_incomplete: true: do not treat such a filter as complete. The field is omitted otherwise.
Needs scope watchlists.restocks:read. Costs 0 points. Strong ETag, 304 supported,
Cache-Control: private, max-age=0.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/watchlists/restocks/events/{id}/deliveryAlert delivery settings of a watchlisted event
Where alerts of an event on the restock watchlist are delivered. An event with no stored settings
gets the defaults the app would use. Channel identifiers and sound settings are never part of
the response. Not on the watchlist or unknown: 404 not_found.
Needs scope watchlists.restocks:read. Costs 0 points. Strong ETag, 304 supported,
Cache-Control: private, max-age=0.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/watchlists/analysisThe analysis watchlist
The events on the organization's analysis watchlist, cursor-paginated and ordered by event id.
An event can be filed more than once in the app; it appears once, under the folder of its
oldest row, and that is the same folder_id with and without the folder_id filter.
Needs scope watchlists.analysis:read and the organization's plan to include Analysis
(otherwise 403 plan_capability_required). Costs 0 points. Strong ETag, 304 supported,
Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 64 |
folder_id query | string (uuid) | Only events filed in this folder. Must be a folder of your organization, else 404 not_found. |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/event-dropsEvent Drops follows
The artists and venues the organization follows for Event Drops (new event alerts), cursor-paginated
by subscription id, plus the organization's subscription limit, current count and Event Drops
delivery settings (tag_everyone, the Discord channel id).
Needs scope event_drops:read.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 64 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/shopify/watchesShopify product watches
The organization's Shopify product watches: product, options and variants as last resolved, the option filter, mute and delivery settings (channel ids only; no sound URL). The list is bounded by the organization's Shopify watch limit and is not paginated.
Needs scope shopify:read.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/channelsDelivery channels
The organization's delivery channels (Discord and Slack): id, name, provider, default and active flags, cursor-paginated by id. Use the ids where other responses name a channel. Webhook URLs are never served.
Needs scope channels:read.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 64 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/alertsThreshold alert rules
The organization's threshold alert rules, cursor-paginated by id, plus every alert destination (name, type and state only: a destination's URL is write-only and its signing secret is never served). Numeric thresholds are decimal strings.
Needs scope alerts:read and the organization's plan to include Alerts (otherwise
403 plan_capability_required).
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 64 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/alerts/triggeredTriggered alert history
When the organization's alert rules fired, newest first, cursor-paginated. Delivery error text and the trigger snapshot are not served.
Needs scope alerts:read and the organization's plan to include Alerts.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 128 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/feedNotification feed (24 h)
The organization's notification history for the last 24 hours, newest first, exactly the
notifications its Feed shows: restocks, price changes, Smart Alerts, Event Drops, TM Queue and
Shopify restocks. Each has a public type and the app's finer kind.
Presale and access codes are never served: extra fields that name or mention a code are dropped
and code parameters (such as Ticketmaster's did) are removed from links. Webhook deliveries
(phase 3) use this same notification shape.
Read it by passing next until it is null. To stay current, poll again later from the first page
and stop at the newest notification you already hold; a notification older than 24 hours is gone.
Needs scope feed:read.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 128 |
type query | string | Only these notification types, comma-separated (for example restock,smart_alert). An unknown type is 400 invalid_query.e.g. restock,price_change |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/smart-alerts/settingsSmart Alerts settings
The organization's Smart Alerts settings. An organization that never saved settings gets the app's
defaults and updated_at: null.
Needs scope smart_alerts:read.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/activityActivity log
The organization's audit log, newest first, cursor-paginated: source, domain, action, status, severity, summary, the actor's role and the entity acted on. IP addresses, user agents, user ids, emails and event metadata are never served; for people and invite entities the entity id and label are null.
Needs scope activity:read, which only an owner's or admin's key can use (as in the app).
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 128 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/watchlists/queueThe TM Queue list
The events on the organization's TM Queue list with their mute, color, channel and notes, cursor-paginated by event id. Events here grant market access.
Needs scope watchlists.queue:read.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 64 |
Responses
If-None-Match validator still matches. No body, 0 points.GET/v1/watchlists/campaignsConcert Week lists
The Concert Week campaigns the organization has access to (with its access state and list limit) and one page of its campaign list entries, cursor-paginated by entry id. A list grants market access only while the access is enabled and the campaign is active.
Needs scope watchlists.campaigns:read.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 64 |
Responses
If-None-Match validator still matches. No body, 0 points.Change your organization's watchlists, Event Drops, Shopify watches and alert rules, and resolve event links. Cost 0 points; writes bucket.
POST/v1/watchlists/restocks/events/{id}/filtersAdd an alert filter
Adds an alert filter to a watchlisted event. rules takes the keys of FilterRules only (any other key
is 400 invalid_filter_rule); the values are validated for the event's platform, as in the app. Leave
rules out to start from your organization's default filter. channel_ids are existing channels of
your organization (GET /v1/channels).
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header | string | The event's configuration version. When sent it must match (412 precondition_failed). |
Request body
Responses
PATCH/v1/watchlists/restocks/events/{id}/deliveryUpdate alert delivery settings
Changes tag_everyone and the alert color of one event. Where alerts go (Discord, Slack, Feed) is a
superadmin setting in the app and cannot be changed here; sound settings are app-only. If-Match is required.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator). Requires If-Match with the event's configuration version (428 precondition_required without it, 412 precondition_failed when stale).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header · required | string | The current version, from ETag of a previous write or of getRestockConfigVersion
(* matches any). Our proxy may deliver the ETag header in weak form, W/"…"; send it as received,
it matches the same version. Missing: 428 precondition_required. Stale: 412 precondition_failed, with the
current version in ETag and details.current_etag. Conditional writes of one organization run
one at a time, so of two writes sent with the same version only the first succeeds. A change made
in the MCOMP app between the check and the write is not caught. |
Request body
Responses
POST/v1/shopify/watchesWatch Shopify products
Resolves 1 to 20 Shopify product links and watches each one. Each result has status ok (with the
watch; created is false when it was already watched) or a code such as invalid_shopify_url,
limit_reached or invalid_request. The organization must have Shopify enabled
(403 provider_disabled). Resolving calls Shopify, so this route is limited to 1 call per 5 seconds per
organization, plus the app's 10 per minute (429 write_rate_limited).
Needs scope shopify:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
POST/v1/alertsCreate threshold alert rules
Creates 1 to 50 threshold alert rules on one event, in one transaction (Alerts plans). Each rule
points at an existing destination of your organization (GET /v1/alerts lists them); another
organization's destination is 403 forbidden. Creating or editing destinations is app-only.
Needs scope alerts:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
POST/v1/watchlists/restocks/eventsAdd an event to the restock watchlist
Adds an event to the regular restock watchlist, with the app's own rules: the organization and module
caps (409 limit_reached with details.limit and details.current), the restock module switch
(403 module_disabled), eligibility (422 event_not_eligible for a past, cancelled or unsupported
event) and the default filters and delivery settings the app creates. Already on the watchlist:
409 already_exists. folder_id must be a restock folder of your organization (else 404 not_found).
The main backend's monitors pick the event up within seconds.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
GET /v1/watchlists/restocks lists it. ETag is its configuration version.RestockWatchlistEventPOST/v1/watchlists/restocks/events/bulkBulk restock watchlist action
Runs one action over up to 200 events: add, remove, set_folder, clear_folder, set_muted_until,
set_event_channels, inherit_event_channels or clear_event_channels. Each event gets its own result
(added, removed, updated, skipped or failed with a reason such as already_tracked,
not_found, past_event, limit_reached or module_disabled). A platform:external_id reference with
no event is reported as failed / not_found under the reference as sent. A malformed reference fails
the whole request (400 invalid_ids).
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limits (100 per minute per key creator, and 60 heavy writes per minute per organization).
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
PATCH/v1/watchlists/restocks/events/{id}Update a restock watchlist event
Changes the folder, notes or mute of one event. Members you leave out are unchanged; null clears
folder_id, notes and muted_until. If-Match is optional here; when sent it must match.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header | string | The event's configuration version. When sent it must match (412 precondition_failed). |
Request body
Responses
DELETE/v1/watchlists/restocks/events/{id}Remove an event from the restock watchlist
Removes one event. Not on the watchlist: 404 not_found.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
POST/v1/watchlists/restocks/foldersCreate a restock folder
Creates a restock watchlist folder. Names are unique per organization (409 already_exists) and 1 to 100 characters.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
PATCH/v1/watchlists/restocks/folders/{folder_id}Rename a restock folder
Renames a folder of your organization.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
folder_id path · required | string (uuid) | A folder of your organization (anything else is 404 not_found). |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
DELETE/v1/watchlists/restocks/folders/{folder_id}Delete a restock folder
Deletes a folder; its events move out of it.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
folder_id path · required | string (uuid) | A folder of your organization (anything else is 404 not_found). |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
PATCH/v1/watchlists/restocks/events/{id}/filters/{filter_id}Update an alert filter
Changes one filter. Members you leave out are unchanged; rules: {} also means no rule change. When you
send rules, rule keys the filter holds outside FilterRules are kept. If-Match is required.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator). Requires If-Match with the event's configuration version (428 precondition_required without it, 412 precondition_failed when stale).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
filter_id path · required | string (uuid) | A filter of this event. |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header · required | string | The current version, from ETag of a previous write or of getRestockConfigVersion
(* matches any). Our proxy may deliver the ETag header in weak form, W/"…"; send it as received,
it matches the same version. Missing: 428 precondition_required. Stale: 412 precondition_failed, with the
current version in ETag and details.current_etag. Conditional writes of one organization run
one at a time, so of two writes sent with the same version only the first succeeds. A change made
in the MCOMP app between the check and the write is not caught. |
Request body
Responses
DELETE/v1/watchlists/restocks/events/{id}/filters/{filter_id}Delete an alert filter
Deletes one filter. If-Match is required.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator). Requires If-Match with the event's configuration version (428 precondition_required without it, 412 precondition_failed when stale).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
filter_id path · required | string (uuid) | A filter of this event. |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header · required | string | The current version, from ETag of a previous write or of getRestockConfigVersion
(* matches any). Our proxy may deliver the ETag header in weak form, W/"…"; send it as received,
it matches the same version. Missing: 428 precondition_required. Stale: 412 precondition_failed, with the
current version in ETag and details.current_etag. Conditional writes of one organization run
one at a time, so of two writes sent with the same version only the first succeeds. A change made
in the MCOMP app between the check and the write is not caught. |
Responses
PUT/v1/watchlists/restocks/events/{id}/filters/orderReorder alert filters
Sets filter priorities (lower first). Filters of other events are ignored. If-Match is required.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator). Requires If-Match with the event's configuration version (428 precondition_required without it, 412 precondition_failed when stale).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header · required | string | The current version, from ETag of a previous write or of getRestockConfigVersion
(* matches any). Our proxy may deliver the ETag header in weak form, W/"…"; send it as received,
it matches the same version. Missing: 428 precondition_required. Stale: 412 precondition_failed, with the
current version in ETag and details.current_etag. Conditional writes of one organization run
one at a time, so of two writes sent with the same version only the first succeeds. A change made
in the MCOMP app between the check and the write is not caught. |
Request body
Responses
PUT/v1/watchlists/restocks/events/{id}/channelsAssign delivery channels
Assigns existing channels of your organization (at most 50) to one event, or inherits the
organization's defaults (channel_override_enabled: false). Creating channels is app-only. A channel of
another organization is 404 not_found. If-Match is required.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator). Requires If-Match with the event's configuration version (428 precondition_required without it, 412 precondition_failed when stale).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header · required | string | The current version, from ETag of a previous write or of getRestockConfigVersion
(* matches any). Our proxy may deliver the ETag header in weak form, W/"…"; send it as received,
it matches the same version. Missing: 428 precondition_required. Stale: 412 precondition_failed, with the
current version in ETag and details.current_etag. Conditional writes of one organization run
one at a time, so of two writes sent with the same version only the first succeeds. A change made
in the MCOMP app between the check and the write is not caught. |
Request body
Responses
GET/v1/watchlists/restocks/events/{id}/config-versionConfiguration version (ETag) of a watchlisted event
The version of one event's restock configuration (its watchlist entry, filters and delivery settings):
the value conditional writes compare If-Match with. It is the same version the app uses, so a change
made in the app also moves it. Every write that changes the configuration returns the new version in
ETag. This is not the ETag of the filters and delivery reads (those validate a response body).
Needs scope watchlists.restocks:write. Costs 0 points and no write token.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Responses
POST/v1/watchlists/restocks/filter-templates/applyApply filter templates
Applies your organization's saved filter templates (1 to 25, one platform) to up to 500 watchlisted
events: append adds their filters, replace replaces each event's filters, only_empty fills events
that have none. preview: true reports what would happen and writes nothing.
Needs scope watchlists.restocks:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limits (100 per minute per key creator, and 60 heavy writes per minute per organization).
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
POST/v1/watchlists/queue/eventsAdd events to TM Queue
Adds up to 200 events to TM Queue under the app's per-platform caps. Per-event results: added, or
failed/skipped with already_tracked, not_found, past_event, unsupported_platform or
limit_reached. Needs your plan to include TM Queue (403 plan_capability_required).
Needs scope watchlists.queue:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limits (100 per minute per key creator, and 60 heavy writes per minute per organization).
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
DELETE/v1/watchlists/queue/events/{id}Remove an event from TM Queue
Removes one event from TM Queue.
Needs scope watchlists.queue:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
POST/v1/watchlists/campaigns/eventsAdd events to Concert Week
Adds up to 200 events to Concert Week while the campaign is active and enabled for your organization
(403 otherwise; 404 not_found when no campaign is configured). A full cap fails the whole call with
409 limit_reached; a partial one marks the overflow limit_reached.
Needs scope watchlists.campaigns:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limits (100 per minute per key creator, and 60 heavy writes per minute per organization).
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
DELETE/v1/watchlists/campaigns/events/{id}Remove an event from Concert Week
Removes one event from Concert Week.
Needs scope watchlists.campaigns:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key. Also counts against the app's own restock write limit (100 per minute per key creator).
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
POST/v1/watchlists/analysis/eventsAdd an event to the analysis watchlist
Adds an event to the analysis watchlist (Analysis plans; 403 plan_capability_required otherwise),
under the organization's cap (409 limit_reached). An event already on the watchlist in another folder is
moved there; in the same folder it is 409 already_exists. folder_id must be an analysis folder.
Needs scope watchlists.analysis:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
POST/v1/watchlists/analysis/events/bulkBulk analysis watchlist action
Runs add, remove, set_folder or clear_folder over up to 200 events. add is all or nothing
against the cap: 409 limit_reached with details.limit, details.current and details.requested.
Needs scope watchlists.analysis:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
DELETE/v1/watchlists/analysis/events/{id}Remove an event from the analysis watchlist
Removes one event.
Needs scope watchlists.analysis:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
id path · required | string | An event UUID, or <platform>:<external_id> (for example ticketmaster:Z7r9jZ1A7abcd). The
platform is one of the values of PlatformName; external_id is at most 128 printable
characters without spaces.max length 200 |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
POST/v1/watchlists/analysis/foldersCreate an analysis folder
Creates an analysis folder (names need not be unique).
Needs scope watchlists.analysis:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
PATCH/v1/watchlists/analysis/folders/{folder_id}Rename an analysis folder
Renames an analysis folder.
Needs scope watchlists.analysis:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
folder_id path · required | string (uuid) | A folder of your organization (anything else is 404 not_found). |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
DELETE/v1/watchlists/analysis/folders/{folder_id}Delete an analysis folder
Deletes an analysis folder.
Needs scope watchlists.analysis:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
folder_id path · required | string (uuid) | A folder of your organization (anything else is 404 not_found). |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
POST/v1/event-drops/subscriptionsFollow an artist or venue
Follows an artist or venue for Event Drops, under the organization's cap (409 limit_reached with
details.limit). Following it again renames it. Matching picks the change up within 30 seconds.
Needs scope event_drops:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
DELETE/v1/event-drops/subscriptions/{subscription_id}Unfollow
Removes one follow.
Needs scope event_drops:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
subscription_id path · required | string (uuid) | An Event Drops follow of your organization. |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
PUT/v1/event-drops/settingsEvent Drops delivery settings
Sets tag_everyone for Event Drops alerts. The channel is set in the app.
Needs scope event_drops:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
PATCH/v1/shopify/watches/{watch_id}Update a Shopify watch
Changes a watch's variant filter and delivery settings. Members you leave out keep their current
values, and the sound settings (app-only) are always kept. If-Match is required and takes the watch's
version: its etag field (in the list and in add and update answers) or the ETag of a previous write,
or * for whatever version it has now (a stale one is 412 precondition_failed with the current
version in ETag and details.current_etag).
Needs scope shopify:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
watch_id path · required | string (uuid) | A Shopify watch of your organization. |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
If-Match header · required | string | The watch's current version: its etag field, or ETag of a previous write (* matches any).
Our proxy may deliver the ETag header in weak form, W/"…"; send it as received, it matches the
same version. Missing: 428 precondition_required. Stale: 412 precondition_failed, with the current
version in ETag and details.current_etag. The version is compared inside the write, so any change
made since, in the API or the MCOMP app, is caught. |
Request body
Responses
DELETE/v1/shopify/watches/{watch_id}Stop watching a Shopify product
Removes one watch.
Needs scope shopify:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
watch_id path · required | string (uuid) | A Shopify watch of your organization. |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
PATCH/v1/alerts/{alert_id}Edit, activate or deactivate a rule
Changes one rule. is_active activates or deactivates it; destination_id: null detaches the destination.
Needs scope alerts:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
alert_id path · required | string (uuid) | An alert rule of your organization. |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
DELETE/v1/alerts/{alert_id}Delete a rule
Deletes one rule.
Needs scope alerts:write. Costs 0 points and one token of the writes bucket (2 per second, burst 10 per organization). Accepts Idempotency-Key.
Parameters
alert_id path · required | string (uuid) | An alert rule of your organization. |
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Responses
POST/v1/events/resolveResolve event links into MCOMP events
Resolves up to 20 event links or provider IDs through the same providers and catalog import the app
uses, so you can add an event MCOMP does not have yet: take events[].id of a resolved result and add
it to a watchlist. An input that is an MCOMP event id, or a platform:external_id MCOMP already has, is
answered from the catalog without calling a provider. provider defaults to ticketmaster; an
unsupported one is 400 invalid_platform with details.supported. Per-input status is resolved,
duplicate, not_found, invalid (for example an AXS link outside AXS ticketing pages), pending or
error. An upstream failure of the whole call is 502 upstream_unavailable.
Needs scope events:resolve. Costs 0 points; it has its own bucket of 30 calls per minute per
organization (429 resolve_rate_limited; X-MCOMP-Resolve-Limit and X-MCOMP-Resolve-Remaining).
Inputs sent to a provider also draw from your organization's input budget (20 per minute,
details.scope org_inputs) and a service-wide budget shared by every organization (about 60 per
minute, details.scope global); when either is spent the call is 429 resolve_rate_limited. A
platform:external_id on another platform than provider is answered not_found without a provider call. The
resolve kill switch, and the writes one, stop it.
Parameters
Idempotency-Key header | string | Optional on every write. 1 to 255 printable ASCII characters, unique per intended write; scoped to
the API key and kept 24 hours. Repeating a request with the same key and the same method, path,
If-Match and body replays the first answer (same status, body and ETag, plus
Idempotent-Replayed: true) without writing again. The same key with a different request is
422 idempotency_key_reused; while the first request is still running (up to 60 seconds) a retry
gets 409 idempotency_in_progress with Retry-After; after that a retry runs it. Answers worth
retrying (5xx, 429, 412, 428) are not stored, unless the write had already been applied.max length 255 |
Request body
Responses
Webhooks push your organization's feed notifications (the FeedNotification shape of GET /v1/feed)
to your HTTPS endpoint as they happen. Manage them with scope webhooks:manage, here or in the app
(Settings > Organization > Webhooks). Creating or changing a webhook also needs feed:read, since a
webhook sends your feed, and nothing is delivered unless your organization is allowed both.
Each delivery is a POST with a JSON body (WebhookPayload, at most 256 KiB) and these headers:
X-MCOMP-Event (the event type), X-MCOMP-Delivery (a UUID, the same on every retry of that
delivery; use it to de-duplicate), X-MCOMP-Signature-256: sha256=<hex> (the HMAC-SHA256 of the
exact body bytes, keyed with the webhook's signing key) and User-Agent: MCOMP-Webhooks/1. Verify
the signature with a constant-time comparison before trusting a body.
Event types: restock, price_change, smart_alert, event_drop, queue, shopify, and ping
(sent when a webhook is created and on request). Any 2xx answer within 10 seconds is a success;
redirects are not followed. A failed attempt is retried after about 1 minute, 5 minutes,
30 minutes, 2 hours, 6 hours and 12 hours (with jitter), then the delivery fails. When every
attempt to a webhook has failed for 3 days, it is switched off (disabled_reason: failing) and
your owners and admins get an app notification; switch it back on when the endpoint works.
Deliveries are at least once and roughly in order, not strictly ordered.
Nothing is delivered while the public API is disabled or suspended for the organization, during a
free trial, or when the user who created the webhook is no longer an owner or admin
(creator_active: false).
GET/v1/webhooksList webhooks
The organization's webhooks, oldest first (at most 10). The signing key is never part of a read.
Needs scope webhooks:manage.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Responses
If-None-Match validator still matches. No body, 0 points.POST/v1/webhooksCreate a webhook
Adds a webhook and queues a ping delivery to it. The answer carries the webhook's
signing_key (whsec_...) this once: store it to verify the X-MCOMP-Signature-256 header of
every delivery. It is never returned again; rotate it if it is lost.
The URL must be public HTTPS on port 443, without credentials or a fragment; every address its
name resolves to must be public (no private, loopback, link-local or reserved ranges), and the
address is checked again at every delivery. An organization can have at most 10 webhooks
(409 webhook_limit_reached). folder_ids must be your organization's restock folders. Unknown
body fields are refused (400 invalid_webhook).
Needs scopes webhooks:manage and feed:read (a webhook sends your feed). Costs 0 points.
Cache-Control: no-store.
Request body
Responses
GET/v1/webhooks/{webhook_id}Get a webhook
One webhook. 404 not_found when it does not exist or belongs to another organization.
Needs scope webhooks:manage.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
webhook_id path · required | string (uuid) | A webhook id from listWebhooks. |
Responses
If-None-Match validator still matches. No body, 0 points.PATCH/v1/webhooks/{webhook_id}Update a webhook
Changes the URL, the event types, the filters or active. Absent fields are unchanged; null or
[] clears a filter. Switching a webhook off fails the deliveries waiting for it; switching it
on clears an automatic switch-off (disabled_reason: failing) and delivers only notifications
created from then on (nothing missed while it was off is replayed).
Needs scopes webhooks:manage and feed:read (a webhook sends your feed). Costs 0 points.
Cache-Control: no-store.
Parameters
webhook_id path · required | string (uuid) | A webhook id from listWebhooks. |
Request body
Responses
DELETE/v1/webhooks/{webhook_id}Delete a webhook
Deletes the webhook and its delivery log. Nothing more is sent to it.
Needs scope webhooks:manage. Costs 0 points. Cache-Control: no-store.
Parameters
webhook_id path · required | string (uuid) | A webhook id from listWebhooks. |
Responses
POST/v1/webhooks/{webhook_id}/rotate-signing-keyRotate the signing key
Replaces the webhook's signing key and returns the new one this once. Attempts made after the rotation are signed with the new key (a delivery already in flight may still carry the old signature), so accept both keys for a short while when you rotate.
Needs scope webhooks:manage. Costs 0 points. Cache-Control: no-store.
Parameters
webhook_id path · required | string (uuid) | A webhook id from listWebhooks. |
Responses
POST/v1/webhooks/{webhook_id}/pingSend a ping
Queues a ping delivery to an active webhook (409 webhook_inactive otherwise). A ping that is
already waiting is returned instead of queuing another.
Needs scope webhooks:manage. Costs 0 points. Cache-Control: no-store.
Parameters
webhook_id path · required | string (uuid) | A webhook id from listWebhooks. |
Responses
GET/v1/webhooks/{webhook_id}/deliveriesDelivery log
The webhook's deliveries of the last 7 days, newest first: state, attempts, the last status code,
latency and a fixed error class. Payloads are not part of the log. Read it by passing
next_cursor until it is null.
Needs scope webhooks:manage.
Costs 0 points (request bucket only). Strong ETag, 304 supported, Cache-Control: private, max-age=0.
Parameters
webhook_id path · required | string (uuid) | A webhook id from listWebhooks. |
limit query | integer | Page size. default 50 · 1 to 100 |
cursor query | string | The next of the previous page. Opaque.max length 128 |
Responses
If-None-Match validator still matches. No body, 0 points.POST/v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliverRedeliver
Queues a new delivery of a finished one (delivered or failed) with the same body and a new
X-MCOMP-Delivery id (redelivery_of names the original). A pending delivery cannot be
redelivered, nor one of a switched-off webhook (409).
Needs scope webhooks:manage. Costs 0 points. Cache-Control: no-store.
Parameters
webhook_id path · required | string (uuid) | A webhook id from listWebhooks. |
delivery_id path · required | string (uuid) | A delivery id from the delivery log (the X-MCOMP-Delivery header). |
Responses
Diagnostics.
GET/v1/_auth/whoamiEcho the authenticated key
Returns the organization id, the key prefix and the key's scopes. Needs no scope. Useful to check that a key works. Costs 0 points.
Responses
GET/healthzLiveness
Static {"ok": true}. No authentication, no database access, no rate limit.
Responses
Schemas
Errorobject
error | object |
|
DateOrDateTimestring
An RFC 3339 timestamp or a bare YYYY-MM-DD date (UTC).
PlatformNamestring
A platform identifier.
Moneystring | null
A decimal string with two fraction digits, or null when unknown.
Whoamiobject
org_id | string (uuid) | |
key_prefix | string | |
scopes | string[] |
Eventobject
id | string (uuid) | |
name | string | |
event_date | string (date-time) | |
first_seen_at | string (date-time) | null | |
last_ingested_at | string (date-time) | null | |
is_active | boolean | |
category | string | null | |
subcategory | string | null | |
venue | Venue | |
artists | Artist[] | |
platforms | EventPlatform[] | |
ticketmaster | Ticketmaster | null | Ticketmaster details, or null when the event has none. |
Venueobject
name | string | |
city | string | null | |
state | string | null | |
state_code | string | null | |
country | string | null | |
country_code | string | null | |
timezone | string | null | |
latitude | number | null | |
longitude | number | null |
Artistobject
name | string | |
type | string | null | |
headliner | boolean |
EventPlatformobject
platform | string | |
external_id | string | |
url_event_id | string | null | |
url | string | null |
Presaleobject
A presale window. Presale and access codes are never exposed.
name | string | null | |
start_at | string (date-time) | |
end_at | string (date-time) | null |
AgeRestrictionsobject
legal_age_enforced | boolean | null | |
age_rule_description | string | null |
Ticketmasterobject
public_sale_start | string (date-time) | null | |
public_sale_end | string (date-time) | null | |
presales | Presale[] | |
segment | string | null | |
genre | string | null | |
subgenre | string | null | |
promoter_name | string | null | |
seatmap_url | string | null | |
ticket_limit_info | string | null | |
is_safetix | boolean | null | |
is_all_inclusive_pricing | boolean | null | |
age_restrictions | AgeRestrictions | null | |
date_status | string | null | |
local_date | string | null | Local event date, YYYY-MM-DD. |
local_time | string | null | Local event time, HH:MM:SS. |
EventSearchPageobject
items | Event[] | |
next_cursor | string | null | Opaque cursor for the next page, null on the last page. |
EventsByIdsobject
items | object[] |
| |||||||||||||||
charged | integer | Points charged by this request. |
RestockLifecycleobject
classification | string | |
observed_at | string (date-time) | |
source_class | string | The inventory source the lifecycle comes from (regular, or preload when there is no regular row). |
RestockPlatformobject
Prices are decimal strings in the platform's listing currency (no currency field).
platform | string | |
captured_at | string (date-time) | |
total_stock | integer | null | |
venue_capacity | integer | null | |
availability_percent | number | null | |
min_price_per_ticket | Money | |
max_price_per_ticket | Money | |
min_price_total | Money | |
max_price_total | Money | |
last_observation_kind | string | one of baseline, restock |
last_restocked_at | string (date-time) | null | When the last restock was observed. Null until a restock has been observed since tracking began; null means "not observed", not "never restocked". |
lifecycle | RestockLifecycle | null |
RestockCurrentobject
event_id | string (uuid) | |
platforms | RestockPlatform[] |
RestockPointobject
One point. Values that are unknown are omitted. Prices are decimal strings.
ts | string (date-time) | Daily points are stamped at midnight America/New_York and carry the day's close. |
marker optional | string | A label of the observation |
stock optional | integer | |
capacity optional | integer | |
availability_percent optional | number | |
min_price_per_ticket optional | string | |
max_price_per_ticket optional | string | |
avg_price_per_ticket optional | string | |
min_price_total optional | string | |
max_price_total optional | string | |
avg_price_total optional | string |
RestockMetadataobject
last_observed_at | string (date-time) | null | |
stale_after_seconds | integer | |
is_stale | boolean |
RestockHistoryobject
event_id | string (uuid) | |
platform | string | |
window | string | one of 3d, 1w, 1m, 6m, all |
points | RestockPoint[] | |
truncated | boolean | True when the series was cut to the newest 4000 points. |
metadata | RestockMetadata |
PrimaryPlatformobject
platform | string | |
captured_at | string (date-time) | |
currency | string | null | ISO currency code of the prices. |
capacity | integer | null | |
stock_available | integer | null | |
available_percent | number | null | |
sold_out | boolean | |
listing_count | integer | null | |
offer_ticket_quantity | integer | null | |
get_in_price | Money | |
min_face_value | Money | |
max_face_value | Money | |
min_total_price | Money | |
max_total_price | Money | |
avg_total_price | Money | |
resale_listing_count | integer | null | |
resale_offer_ticket_quantity | integer | null |
PrimaryCurrentobject
event_id | string (uuid) | |
platforms | PrimaryPlatform[] |
PrimaryPointobject
One bucket. Values that are unknown are omitted. Prices are decimal strings in the series currency.
bucket_start | string (date-time) | Daily buckets start at midnight UTC. |
last_captured_at | string (date-time) | |
sample_count | integer | |
capacity optional | number | |
stock_available optional | number | |
available_percent optional | number | |
listing_count optional | number | |
offer_ticket_quantity optional | number | |
get_in_price optional | string | |
min_total_price optional | string | |
max_total_price optional | string | |
avg_total_price optional | string | |
sold_out | boolean |
PrimaryHistoryobject
event_id | string (uuid) | |
platform | string | |
range | string | one of 24h, 3d, 7d, 30d, 6m, all |
currency | string | null | |
points | PrimaryPoint[] | |
truncated | boolean | True when the series was cut to the newest 4000 points. |
PrimaryZoneobject
zone_key | string | |
zone_name | string | |
zone_description | string | null | |
captured_at | string (date-time) | |
currency | string | null | |
stock_available | integer | null | |
listing_count | integer | null | |
offer_ticket_quantity | integer | null | |
sold_out | boolean | |
get_in_price | Money | |
min_total_price | Money | |
max_total_price | Money | |
stock_change_24h | integer | null | |
stock_change_percent_24h | number | null | |
get_in_price_change_24h | Money | |
get_in_price_change_percent_24h | number | null | |
status_label | string | |
updated_at | string (date-time) | null |
PrimaryZonesobject
event_id | string (uuid) | |
platform | string | |
zones | PrimaryZone[] |
SecondaryPlatformobject
platform | string | |
captured_at | string (date-time) | |
currency | string | null | |
stock_count | integer | null | |
listed_count | integer | null | |
get_in_price | Money | |
avg_listing_price | Money | |
min_listing_price | Money | |
max_listing_price | Money | |
get_in_price_all_in | Money | |
avg_listing_price_all_in | Money | |
min_listing_price_all_in | Money | |
max_listing_price_all_in | Money |
SecondaryCurrentobject
event_id | string (uuid) | |
platforms | SecondaryPlatform[] |
SecondarySectionobject
SecondarySectionsobject
event_id | string (uuid) | |
platform | string | |
sections | SecondarySection[] |
SecondaryPointobject
bucket_start | string (date-time) | Daily buckets start at midnight UTC. |
last_captured_at | string (date-time) | |
sample_count | integer | |
value | number | string | null | A number for count metrics, a decimal string for price metrics, null when unknown. |
SecondaryHistoryobject
event_id | string (uuid) | |
platform | string | |
scope | string | one of event, section |
section_id | string (uuid) | null | |
metric | string | one of stock_count, listed_count, get_in_price, avg_listing_price, min_listing_price, max_listing_price |
days | integer | |
currency | string | null | Set for price metrics. |
points | SecondaryPoint[] | |
truncated | boolean | True when the series was cut to the newest 4000 points. |
AvailabilityCurrentobject
platform | string | |
captured_at | string (date-time) | |
is_complete | boolean | |
stock_available | integer | |
capacity | integer | null | |
available_percent | number | null | |
source | string |
AvailabilitySectionobject
section_id | string (uuid) | null | |
section_name | string | |
section_group | string | |
platform | string | |
captured_at | string (date-time) | |
is_complete | boolean | |
stock_available | integer | |
capacity | integer | null | |
available_percent | number | null | |
source | string | one of reported, derived |
AvailabilityDetailobject
event_id | string (uuid) | |
event | AvailabilityCurrent | null | |
sections | AvailabilitySection[] | |
truncated | boolean | True when the event has more than 1000 sections. |
AvailabilityPointobject
captured_at | string (date-time) | |
platform | string | |
is_complete | boolean | |
stock_available | integer | |
capacity | integer | null | |
available_percent | number | null | |
source | string | one of reported, derived |
AvailabilityHistoryobject
event_id | string (uuid) | |
scope | string | one of event, section |
section_id | string (uuid) | null | |
granularity | string | one of hourly, daily, weekly, monthly |
days | integer | |
points | AvailabilityPoint[] | |
truncated | boolean | True when the series was cut to the newest 4000 points. |
EventTrendPointobject
bucket_start | string (date-time) | |
min_price | string | null | |
max_price | string | null | |
total_listings | integer | null | |
total_tickets | integer | null |
EventTrendobject
event_id | string (uuid) | |
granularity | string | one of minutely, hourly, daily, weekly, monthly |
days | integer | |
points | EventTrendPoint[] | |
truncated | boolean | True when the series was cut to the newest 4000 points. |
SectionTrendPointobject
bucket_start | string (date-time) | |
ticket_type | string | null | |
section_name | string | null | |
section_group | string | null | |
min_price | string | null | |
max_price | string | null | |
avg_price | string | null | |
total_quantity | integer | null | |
listing_count | integer | null |
SectionTrendobject
event_id | string (uuid) | |
section_id | string (uuid) | |
granularity | string | The granularity served. one of hourly, daily, weekly, monthly |
requested_granularity | string | one of minutely, hourly, daily, weekly, monthly |
days | integer | |
points | SectionTrendPoint[] | |
truncated | boolean | True when the series was cut to the newest 4000 points. |
ZoneTrendPointobject
bucket_start | string (date-time) | |
zone | string | Unknown when the listings have no zone. |
price_per_ticket | string | null | |
sections | string[] | |
total_quantity | integer | null | |
listing_count | integer | null |
ZoneTrendobject
event_id | string (uuid) | |
granularity | string | one of minutely, hourly, daily, weekly, monthly |
days | integer | |
points | ZoneTrendPoint[] | |
truncated | boolean | True when the series was cut to the newest 4000 points. |
Listingobject
platform | string | |
section_id | string (uuid) | null | |
section_name | string | |
row | string | null | |
seat_from | integer | null | |
seat_to | integer | null | |
zone | string | null | |
zone_description | string | null | |
quantity | integer | |
ticket_type | string | null | |
price_per_ticket | string | |
price_total | string | null | |
service_charges | string | null | |
facility_fees | string | null | |
total_tax | string | null | |
first_seen_at | string (date-time) | |
last_seen_at | string (date-time) |
ListingsPageobject
event_id | string (uuid) | |
listings | Listing[] | |
next_cursor | string | null | Pass as cursor for the next page; null on the last page. |
SeatPlaceobject
place_id | string | |
section | string | |
row | string | |
seat | string |
SeatEntryobject
ts | string (date-time) | |
kind | string | one of listed, removed, price_changed, held, baseline |
lane | string | one of standard, resale |
all_in | string | null | |
price | string | null | |
prev_all_in | string | null | |
ticket_type | string | null | |
held_seconds | integer | null | Set on held entries. |
reconciled | boolean | True when a snapshot found the change rather than a live update. |
SeatHistoryobject
event_id | string (uuid) | |
days | integer | |
place | SeatPlace | |
entries | SeatEntry[] | |
truncated | boolean |
SectionSeatEntryobject
place_id | string | |
section | string | |
row | string | |
seat | string | |
ts | string (date-time) | |
kind | string | one of listed, removed, price_changed, held, baseline |
lane | string | one of standard, resale |
all_in | string | null | |
price | string | null | |
prev_all_in | string | null | |
ticket_type | string | null | |
held_seconds | integer | null | |
reconciled | boolean |
SectionSeatHistoryobject
event_id | string (uuid) | |
days | integer | |
entries | SectionSeatEntry[] | |
truncated | boolean |
MapViewBoxobject
width | number | |
height | number |
MapShapeobject
id | string | |
segment_category | string | null | |
path | string | SVG path data in the view box. |
section_names | string[] |
MapBoundsobject
min_x | number | |
min_y | number | |
width | number | |
height | number |
MapBoundsSectionobject
id | string | |
label | string | |
x | number | |
y | number | |
width | number | |
height | number | |
group_label | string | null |
EventMapobject
event_id | string (uuid) | |
platform | string | |
kind | string | one of svg-sections, section-bounds, none |
reason | string | null | Set when kind is none.one of not_available, map_geometry_not_available, map_metadata_pending, map_metadata_failed, null |
map_version | string | null | |
view_box | MapViewBox | null | |
shapes | MapShape[] | The SVG section shapes (svg-sections); empty otherwise. |
bounds | MapBounds | null | |
sections | MapBoundsSection[] | The section boxes (section-bounds); empty otherwise. |
updated_at | string (date-time) | null |
FilterOptionsobject
event_id | string (uuid) | |
platform | string | |
sections | string[] | |
rows | string[] | |
zones | string[] | |
ticket_types | string[] | |
updated_at | string (date-time) | null |
InsightBadgeobject
key | string | |
label | string |
EventInsightsobject
event_id | string (uuid) | |
platform | string | |
available | boolean | False when there is no primary data for the platform. |
captured_at | string (date-time) | null | |
freshness_state | string | null | |
currency | string | null | |
capacity | integer | null | |
stock_available | integer | null | |
available_percent | number | null | |
sold_out | boolean | |
sold_out_since | string (date-time) | null | |
get_in_price | string | null | |
min_total_price | string | null | |
max_total_price | string | null | |
avg_total_price | string | null | |
stock_change_4h | integer | null | |
stock_change_percent_4h | number | null | |
stock_change_24h | integer | null | |
stock_change_percent_24h | number | null | |
stock_change_7d | integer | null | |
stock_change_percent_7d | number | null | |
get_in_price_change_24h | string | null | |
get_in_price_change_percent_24h | number | null | |
get_in_price_change_7d | string | null | |
get_in_price_change_percent_7d | number | null | |
secondary_get_in_price | string | null | |
secondary_listed_count | integer | null | |
secondary_vs_primary_get_in | string | null | |
secondary_vs_primary_get_in_percent | number | null | |
available_zone_count | integer | |
sold_out_zone_count | integer | |
priced_section_count | integer | null | |
profitable_section_count | integer | null | |
best_section_name | string | null | |
best_spread_all_in | string | null | |
grade_a_count | integer | null | |
grade_b_count | integer | null | |
best_score_section_name | string | null | |
best_score | integer | null | |
best_score_grade | string | null | |
best_score_margin_pct | number | null | |
best_score_target_price | string | null | |
primary_sold_pct | number | null | |
reason_badges | InsightBadge[] | |
quality_flags | string[] |
SectionMarketRowobject
section_key | string | |
section_name | string | |
zone_key | string | null | |
zone_name | string | null | |
primary_platform | string | null | |
primary_captured_at | string (date-time) | null | |
primary_currency | string | null | |
primary_stock | integer | null | |
primary_listing_count | integer | null | |
primary_get_in_all_in | string | null | |
primary_max_all_in | string | null | |
primary_sold_out | boolean | null | |
secondary_captured_at | string (date-time) | null | |
secondary_currency | string | null | |
secondary_stock | integer | null | |
secondary_listed_count | integer | null | |
secondary_get_in_pre_fee | string | null | |
secondary_get_in_all_in | string | null | |
secondary_avg_all_in | string | null | |
secondary_match | string | null | exact or combined section match. |
demand_badge | string | null | |
location_score | number | null | |
risk_tags | string[] | |
spread_all_in | string | null | Resale all-in get-in minus primary all-in get-in. |
updated_at | string (date-time) |
SectionMarketZoneobject
zone_key | string | |
zone_name | string | |
priced | integer | |
profitable | integer | |
best_spread_all_in | string | null | |
best_grade | string | null | |
has_restock_watch | boolean |
SectionMarketobject
event_id | string (uuid) | |
sections | SectionMarketRow[] | |
zones | SectionMarketZone[] |
SectionScoreRowobject
section_key | string | |
grade | string | null | A, B or C. |
score | integer | null | |
restock_watch | boolean | |
margin_pct | number | null | |
net_resale | string | null | |
target_price | string | null | |
reasons | string[] | |
risks | string[] |
SectionScoresobject
event_id | string (uuid) | |
sections | SectionScoreRow[] |
M3Pickobject
event_id | string (uuid) | |
event_name | string | |
venue_name | string | |
venue_city | string | null | |
venue_state | string | null | |
venue_country | string | null | |
category | string | null | |
event_date | string (date-time) | |
headliner_artist_name | string | null | |
primary_platform | string | |
primary_currency | string | null | |
primary_capacity | integer | null | |
primary_stock_available | integer | null | |
primary_available_percent | number | null | |
primary_sold_out | boolean | |
primary_get_in_price | string | null | |
secondary_platform | string | null | |
secondary_currency | string | null | |
secondary_listed_count | integer | null | |
secondary_get_in_price | string | null | |
spread_amount | string | null | |
spread_percent | number | null | |
primary_supply_percent | number | null | |
secondary_to_primary_supply_ratio | number | null | |
m3_score | number | |
m3_rank_bucket | string | one of elite, strong, viable, borderline |
reason_badges | InsightBadge[] | |
risk_flags | InsightBadge[] | |
computed_at | string (date-time) | |
primary_captured_at | string (date-time) | null |
M3PicksPageobject
bucket | string | one of default, elite, strong, viable, borderline |
picks | M3Pick[] |
ActivityEventobject
event_id | string (uuid) | |
event_name | string | |
platform | string | |
venue_name | string | null | |
event_date | string (date-time) | null | |
artist_name | string | null | |
alerts | integer | |
seats | integer | null | Distinct restocked seats; null when the alerts carried no seat numbers. |
largest_alert | integer | null | |
last_restocked_at | string (date-time) |
ActivityGroupobject
name | string | |
events | integer | |
seats | integer | null | |
alerts | integer | |
largest_alert | integer | null | |
last_restocked_at | string (date-time) |
ActivityHourobject
bucket_start | string (date-time) | |
seats | integer | |
alerts | integer |
ActivityTotalsobject
seats | integer | |
events | integer | |
alerts | integer | |
events_without_seat_numbers | integer |
RestockActivityobject
window | string | one of 24h |
window_start | string (date-time) | |
window_end | string (date-time) | |
totals | ActivityTotals | |
peak_hour | ActivityHour | null | |
hourly | ActivityHour[] | |
events | ActivityEvent[] | |
venues | ActivityGroup[] | |
artists | ActivityGroup[] |
SecondarySummaryobject
as_of | string (date-time) | |
tracked | integer | |
comparable | integer | |
above | integer | |
above_strong | integer | |
at_cost | integer | |
below | integer | |
not_comparable | integer | |
buckets | integer[] | |
bucket_start_percent | number | |
bucket_width_percent | number | |
strong_spread_percent | number |
Stockobject
items | object[] |
| ||||||||||||||||||||||||
charged | integer | Points charged by this request. |
Changesobject
changes | object[] |
| ||||||||||||
next | string | Opaque cursor to pass as since. Reveals the platform-wide timestamp of the last entry examined. | ||||||||||||
has_more | boolean |
Orgobject
id | string (uuid) | |||||||||||||||||||||||||
name | string | |||||||||||||||||||||||||
plan | string | |||||||||||||||||||||||||
capabilities | object |
| ||||||||||||||||||||||||
limits | object |
| ||||||||||||||||||||||||
api | object |
| ||||||||||||||||||||||||
key | object |
|
Folderobject
id | string (uuid) | |
name | string |
RestockWatchlistEventobject
event_id | string (uuid) | |
folder_id | string (uuid) | null | |
muted_until | string (date-time) | null | |
smart_when_muted | boolean | null | |
notes | string | null | |
created_at | string (date-time) | |
platform | string | The event's primary platform. |
filter_count | integer | Every filter configured for the event |
RestockWatchlistPageobject
folders | Folder[] | |
events | RestockWatchlistEvent[] | |
next | string | null | Opaque cursor for the next page |
AnalysisWatchlistEventobject
event_id | string (uuid) | |
folder_id | string (uuid) | null | |
created_at | string (date-time) |
AnalysisWatchlistPageobject
folders | Folder[] | |
events | AnalysisWatchlistEvent[] | |
next | string | null | Opaque cursor for the next page |
FilterRulesobject
The allowlisted rule keys only. Everything else stored with the filter is dropped. See
rules_incomplete on the filter.
version optional | integer | |||||||
sections optional | string[] | |||||||
rows optional | string[] | |||||||
zones optional | string[] | |||||||
exclude_ticket_types optional | string[] | |||||||
ticket_type_exclude optional | string[] | |||||||
price_per_ticket_ranges optional | PriceRanges | |||||||
price_total_ranges optional | PriceRanges | |||||||
singles optional | boolean | |||||||
doubles optional | boolean | |||||||
min_consecutive_seats optional | integer | |||||||
resale optional | boolean | |||||||
include_accessibility optional | boolean | |||||||
minimum_count optional | integer | |||||||
maximum_count optional | integer | |||||||
seat_number_mode optional | string | one of include, exclude | ||||||
seat_number_ranges optional | object[] |
|
PriceRangesobject[]
min | number | null | |
max | number | null |
Filterobject
id | string (uuid) | |
name | string | |
priority | integer | null | |
is_active | boolean | |
rules | FilterRules | |
rules_incomplete optional | boolean | Present (true) only when an allowlisted rule was dropped because of its type or size; treat the rules as incomplete. always true |
alert_color_hex | string | null | |
tag_everyone | boolean | |
channel_override_enabled | boolean | |
include_non_restocked_context | boolean | |
notes | string | null | |
created_at | string (date-time) | |
updated_at | string (date-time) |
Deliveryobject
send_discord | boolean | |
send_slack | boolean | |
send_feed | boolean | |
channel_override_enabled | boolean | |
tag_everyone | boolean | |
alert_color_hex | string | null |
NextCursorstring | null
Opaque cursor for the next page, null on the last page.
EventDropSubscriptionobject
id | string (uuid) | |
entity_type | string | one of artist, venue |
entity_id | string | The provider's artist or venue id. |
display_name | string | |
created_at | string (date-time) |
EventDropDeliveryobject
tag_everyone | boolean | |
discord_channel_id | string (uuid) | null | A channel id from GET /v1/channels. |
EventDropsPageobject
subscriptions | EventDropSubscription[] | |
limit | integer | The organization's subscription cap. |
count | integer | How many subscriptions the organization has. |
delivery | EventDropDelivery | |
next | NextCursor |
ShopifyProductOptionobject
name | string | |
values | string[] |
ShopifyVariantOptionobject
name | string | |
value | string |
ShopifyWatchVariantobject
id | string | |
title | string | |
available | boolean | |
options | ShopifyVariantOption[] |
ShopifyWatchDeliveryobject
send_discord | boolean | |
send_slack | boolean | |
send_feed | boolean | |
channel_override | boolean | |
channel_ids | string (uuid)[] | |
tag_everyone | boolean | |
alert_color_hex | string | null |
ShopifyWatchobject
id | string (uuid) | |
state | string | one of active, pending, paused |
url | string | The product page. |
title | string | null | |
vendor | string | null | |
product_type | string | null | |
image_url | string | null | |
options | ShopifyProductOption[] | |
variants | ShopifyWatchVariant[] | |
filter | ShopifyProductOption[] | The selected option values; empty means any variant. |
needs_review | boolean | The filter no longer matches the product's options. |
muted_until | string (date-time) | null | |
delivery | ShopifyWatchDelivery | |
last_restock_at | string (date-time) | null | |
created_at | string (date-time) | |
updated_at | string (date-time) | |
etag | string | The watch's version. Send it as If-Match on updateShopifyWatch. |
ShopifyWatchesobject
watches | ShopifyWatch[] | |
count | integer |
Channelobject
id | string (uuid) | |
name | string | |
provider | string | e.g. "discord", "slack" |
is_default | boolean | |
is_active | boolean |
ChannelsPageobject
channels | Channel[] | |
next | NextCursor |
AlertRuleobject
id | string (uuid) | |
event_id | string (uuid) | |
section_id | string (uuid) | null | |
section_name | string | null | |
destination_id | string (uuid) | null | |
alert_type | string | |
risk_level | string | |
threshold_operator | string | |
threshold_value | string | A decimal string. |
price_point | string | null | A decimal string. |
include_fees | boolean | |
composite | boolean | A rule with several conditions; the threshold fields then do not describe it fully. |
is_active | boolean | |
is_persistent | boolean | |
retrigger_cooldown_hours | integer | |
trigger_count | integer | |
last_triggered_at | string (date-time) | null | |
notes | string | null | |
created_at | string (date-time) | null | |
updated_at | string (date-time) | null |
AlertDestinationobject
id | string (uuid) | |
name | string | |
type | string | one of discord_webhook, slack_webhook, generic_webhook |
is_active | boolean | |
disabled_reason | string | null | |
last_delivery_at | string (date-time) | null | |
created_at | string (date-time) |
AlertsPageobject
alerts | AlertRule[] | |
destinations | AlertDestination[] | Every destination of the organization, on every page. |
next | NextCursor |
TriggeredAlertobject
id | string (uuid) | |
alert_id | string (uuid) | |
event_id | string (uuid) | |
destination_id | string (uuid) | null | |
threshold_operator | string | |
threshold_value | string | A decimal string. |
current_value | string | The value that crossed the threshold |
status | string | null | |
delivery_attempts | integer | |
triggered_at | string (date-time) | |
delivered_at | string (date-time) | null |
TriggeredAlertsPageobject
triggered | TriggeredAlert[] | |
next | NextCursor |
FeedEventobject
The event, Shopify product or new event the notification is about.
name | string | |
category | string | null | |
external_id | string | null | The provider's event id. |
url | string | null | The event or product link |
thumbnail | string | null | |
local_date | string | null | |
local_time | string | null | |
datetime | string | null | |
venue_name | string | null | |
venue_city | string | null | |
venue_state | string | null | |
venue_country | string | null | |
venue_address | string | null | |
total_stock | integer | null | |
venue_capacity | integer | null |
FeedChannelobject
id | string | |
name | string | |
provider | string |
FeedItemobject
FeedLinkobject
platform | string | |
url | string |
FeedFieldobject
name | string | |
value | string |
FeedSmartTriggerobject
kind | string | |
reason | string | null | |
display_value | string | null | |
section | string | null | |
row | string | null | |
ticket_type | string | null | |
unique_seats | integer | |
preload_note | string | null |
FeedSmartobject
kind | string | |
reason | string | null | |
lookback_hours | integer | null | |
observed_at | string (date-time) | null | |
section | string | null | |
row | string | null | |
ticket_type | string | null | |
unique_seats | integer | |
suppressed_count | integer | |
preload_note | string | null | |
triggers | FeedSmartTrigger[] |
FeedDetailsobject
links | FeedLink[] | |
fields | FeedField[] | Extra labelled lines. Any line that names or mentions a code is dropped. |
queue_detail | string | null | |
entity_type | string | null | For Event Drops |
entity_id | string | null | |
smart | FeedSmart | null |
FeedShopifyOptionobject
name | string | |
value | string |
FeedShopifyVariantobject
id | string | |
title | string | |
available | boolean | |
options | FeedShopifyOption[] |
FeedShopifyobject
watch_id | string (uuid) | null | |
product_id | string | null | |
matched_variants | FeedShopifyVariant[] |
FeedNotificationobject
id | string (uuid) | |
type | string | one of restock, price_change, smart_alert, event_drop, queue, shopify |
kind | string | The app's finer notification type, for example smart_alert_new_section. |
created_at | string (date-time) | |
event_id | string (uuid) | null | |
platform | string | null | |
event | FeedEvent | |
filter_id | string (uuid) | null | |
filter_name | string | null | |
folder_id | string (uuid) | null | |
folder_name | string | null | |
campaign_id | string (uuid) | null | |
campaign_slug | string | null | |
campaign_run_year | integer | null | |
event_notes | string | null | Your organization's own note on the event, as the Feed shows it. |
filter_notes | string | null | |
restock_source | string | null | |
restocked_count | integer | |
currency | string | null | |
alert_color_hex | string | null | |
channels | FeedChannel[] | The delivery channels it went to (no webhook URLs). |
items | FeedItem[] | |
details | FeedDetails | |
shopify | FeedShopify | null | The product side of a Shopify notification, null for every other type. |
FeedPageobject
notifications | FeedNotification[] | |
next | NextCursor |
SmartAlertSettingsobject
enabled | boolean | |
lookback_hours | integer | |
suppression_window_minutes | integer | |
significant_new_seats_threshold | integer | |
smart_when_muted_default | boolean | |
new_seat_alerts_enabled | boolean | |
source_mode | string | one of preload, regular, both |
discord_channel_id | string (uuid) | null | |
updated_at | string (date-time) | null |
Activityobject
id | string (uuid) | ||||||||||
created_at | string (date-time) | ||||||||||
source | string | one of user, system | |||||||||
domain | string | ||||||||||
action | string | ||||||||||
status | string | one of success, denied, failed, retry | |||||||||
severity | string | one of info, warning, error, critical | |||||||||
summary | string | ||||||||||
actor | object |
| |||||||||
entity | object |
|
ActivityPageobject
activities | Activity[] | |
next | NextCursor |
QueueEventobject
event_id | string (uuid) | |
muted_until | string (date-time) | null | |
tag_everyone | boolean | |
alert_color_hex | string | null | |
channel_id | string (uuid) | null | |
notes | string | null | |
created_at | string (date-time) | |
updated_at | string (date-time) |
QueuePageobject
events | QueueEvent[] | |
next | NextCursor |
Campaignobject
id | string (uuid) | |
slug | string | |
run_year | integer | |
display_name | string | |
platform | string | |
status | string | one of draft, active, closed |
starts_at | string (date-time) | null | |
ends_at | string (date-time) | null | |
enabled | boolean | Your organization's access to the campaign. |
watchlist_limit | integer |
CampaignEventobject
id | string (uuid) | |
campaign_id | string (uuid) | |
event_id | string (uuid) | |
created_at | string (date-time) |
CampaignsPageobject
campaigns | Campaign[] | Every campaign your organization has access to, on every page. |
events | CampaignEvent[] | |
next | NextCursor |
AddEventRequestobject
event_id | string | An event UUID or platform:external_id., maxLength: 200 |
folder_id optional | string (uuid) | null |
UpdateRestockEventRequestobject
folder_id optional | string (uuid) | null | null (or empty) removes the event from its folder. |
notes optional | string | null | |
muted_until optional | string (date-time) | null | null (or empty) unmutes. |
smart_when_muted optional | boolean | null |
RestockBulkRequestobject
action | string | one of add, remove, set_folder, clear_folder, set_muted_until, set_event_channels, inherit_event_channels, clear_event_channels |
event_ids | string[] | |
folder_id optional | string (uuid) | null | For add and set_folder. |
channel_ids optional | string (uuid)[] | For set_event_channels (existing channels), or at most one on add. |
muted_until optional | string (date-time) | null | For set_muted_until; null unmutes. |
smart_when_muted optional | boolean | null | |
filter_platform optional | string | With filters on add: the platform the filters are written for. |
filters optional | FilterCreateRequest[] | On add, replaces the default filters (an empty array adds the events with no filters). |
AnalysisBulkRequestobject
action | string | one of add, remove, set_folder, clear_folder |
event_ids | string[] | |
folder_id optional | string (uuid) | null |
EventIdsRequestobject
event_ids | string[] |
FolderRequestobject
name | string |
FilterCreateRequestobject
name | string | |
priority optional | integer | |
rules optional | FilterRules | |
is_active optional | boolean | |
channel_override_enabled optional | boolean | |
include_non_restocked_context optional | boolean | |
tag_everyone optional | boolean | |
alert_color_hex optional | string | null | e.g. "#FF8800" |
notes optional | string | null | |
channel_ids optional | string (uuid)[] |
FilterUpdateRequestobject
name optional | string | |
priority optional | integer | |
rules optional | FilterRules | |
is_active optional | boolean | |
channel_override_enabled optional | boolean | |
include_non_restocked_context optional | boolean | |
tag_everyone optional | boolean | |
alert_color_hex optional | string | null | |
notes optional | string | null | |
channel_ids optional | string (uuid)[] | Replaces the filter's channels; [] clears them. |
ReorderRequestobject
filters | object[] |
|
DeliveryRequestobject
tag_everyone optional | boolean | |
alert_color_hex optional | string | null |
ChannelsRequestobject
channel_override_enabled | boolean | |
channel_ids optional | string (uuid)[] |
ApplyTemplatesRequestobject
template_ids | string (uuid)[] | |
mode | string | one of append, replace, only_empty |
event_ids | string[] | |
preview optional | boolean |
SubscriptionRequestobject
entity_type | string | one of artist, venue |
entity_id | string | |
display_name | string |
EventDropSettingsRequestobject
tag_everyone | boolean |
ShopifyOptionSelectionobject
name | string | |
values | string[] |
ShopifyDeliveryRequestobject
send_discord optional | boolean | |
send_slack optional | boolean | |
send_feed optional | boolean | |
channel_override optional | boolean | |
channel_ids optional | string (uuid)[] | |
tag_everyone optional | boolean | |
alert_color_hex optional | string | null |
ShopifyAddRequestobject
watches | object[] |
|
ShopifyUpdateRequestobject
filter optional | ShopifyOptionSelection[] | |
delivery optional | ShopifyDeliveryRequest |
AlertRuleRequestobject
alert_type | string | one of section, price, section_and_price, section_group, capacity_availability_percent, capacity_availability_count, composite_stock_count | ||||||
section_id optional | string (uuid) | null | |||||||
section_name optional | string | null | |||||||
section_group optional | string | null | |||||||
price_point optional | number | null | |||||||
threshold_operator | string | one of eq, lt, lte, gt, gte | ||||||
threshold_value | integer | |||||||
destination_id | string (uuid) | |||||||
is_persistent optional | boolean | |||||||
retrigger_cooldown_hours optional | integer | |||||||
include_fees optional | boolean | |||||||
risk_level optional | string | one of low, medium, high | ||||||
notes optional | string | null | |||||||
composite_filter optional | object | null |
|
AlertRulesRequestobject
event_id | string | |
rules | AlertRuleRequest[] |
AlertRuleUpdateRequestobject
is_active optional | boolean | |
threshold_value optional | integer | |
threshold_operator optional | string | one of eq, lt, lte, gt, gte |
is_persistent optional | boolean | |
risk_level optional | string | one of low, medium, high |
destination_id optional | string (uuid) | null | null detaches the destination. |
notes optional | string |
ResolveRequestobject
provider optional | string | One of axs, carnegiehall, gametime, metopera, mlb, paciolan, seatgeek, ticketmaster, ticketweb, tickpick, vividseats. carnegiehall takes item numbers and carnegiehall.org event links; metopera takes item numbers and metopera.org links that carry itemNumber (SmartSeat). Each is available once its module is launched (until then it answers invalid_platform and is left out of supported). |
inputs | string[] |
Deletedobject
id | string | The id of what was removed (for watchlist entries, the event id). |
deleted | boolean | always true |
BulkResultobject
event_id | string | The event UUID, or the reference as sent when it matched no event. |
status | string | one of added, removed, updated, skipped, failed |
reason optional | string | Stable code, for example already_tracked, not_found, past_event, limit_reached, module_disabled, unsupported_platform. |
BulkResponseobject
action | string | |
requested | integer | |
succeeded | integer | |
failed | integer | |
results | BulkResult[] |
FilterListobject
filters | Filter[] |
EventChannelsobject
channel_override_enabled | boolean | |
channel_ids | string (uuid)[] |
ConfigVersionobject
event_id | string (uuid) | |
etag | string | The version; send it as If-Match. |
ApplyTemplateResultobject
event_id | string | |
status | string | one of updated, skipped, failed |
reason optional | string | For example not_tracked, platform_mismatch, existing_filters, not_found. |
filter_count optional | integer |
ApplyTemplatesResultobject
mode | string | |
platform | string | |
requested | integer | |
updated | integer | |
skipped | integer | |
failed | integer | |
results | ApplyTemplateResult[] |
AlertRulesCreatedobject
alerts | AlertRule[] | |
count | integer |
ShopifyAddResultobject
url | string | |
status | string | ok, or why this link was not watched (for example invalid_shopify_url, limit_reached). |
created | boolean | |
watch optional | ShopifyWatch |
ShopifyAddResultsobject
results | ShopifyAddResult[] |
ResolvedEventobject
id | string (uuid) | null | The MCOMP event id; null for a match that was not imported. |
platform | string | |
external_id | string | |
url | string | null | |
name | string | |
event_date | string | null | |
local_date | string | null | |
venue_name | string | null | |
venue_city | string | null | |
venue_state | string | null | |
country_code | string | null |
ResolveResultobject
input | string | |
status | string | one of resolved, duplicate, not_found, invalid, pending, error |
events | ResolvedEvent[] |
ResolveResponseobject
provider | string | |
results | ResolveResult[] |
WebhookEventTypestring
Webhookobject
id | string (uuid) | |
url | string (uri) | |
event_types | WebhookEventType[] | |
folder_ids | string (uuid)[] | Only notifications filed in these restock folders (empty means any). |
event_ids | string (uuid)[] | Only notifications about these events (empty means any). Every non-empty filter must match. |
active | boolean | |
disabled_reason | string | null | failing when every delivery failed for 3 days and MCOMP switched the webhook off.one of failing, null |
disabled_at | string (date-time) | null | |
last_success_at | string (date-time) | null | |
last_failure_at | string (date-time) | null | |
creator_active | boolean | False when the user who created the webhook is no longer an owner or admin; nothing is delivered then. |
created_at | string (date-time) | |
updated_at | string (date-time) |
WebhookListobject
webhooks | Webhook[] |
WebhookCreateobject
url | string (uri) | Public HTTPS on port 443. |
event_types | WebhookEventType[] | |
folder_ids optional | string (uuid)[] | null | |
event_ids optional | string (uuid)[] | null |
WebhookUpdateobject
url optional | string (uri) | |
event_types optional | WebhookEventType[] | |
folder_ids optional | string (uuid)[] | null | |
event_ids optional | string (uuid)[] | null | |
active optional | boolean |
WebhookCreatedobject
webhook | Webhook | |
signing_key | string | The HMAC key (whsec_...) that signs every delivery. Returned only here and by rotate. |
WebhookSigningKeyobject
signing_key | string | The new HMAC key (whsec_...). Returned only here. |
WebhookDeletedobject
id | string (uuid) | |
deleted | boolean | always true |
WebhookDeliveryobject
id | string (uuid) | The X-MCOMP-Delivery header value. |
webhook_id | string (uuid) | |
event_type | string | one of restock, price_change, smart_alert, event_drop, queue, shopify, ping |
notification_id | string (uuid) | null | The feed notification it carries (null for a ping). |
state | string | one of pending, delivered, failed |
attempt | integer | Attempts made so far. |
http_status | integer | null | Your endpoint's last HTTP status. |
latency_ms | integer | null | |
error | string | null | Why the last attempt failed or the delivery was skipped: http_status, timeout, connect,
tls, unsafe_destination, too_large, error, not_eligible, webhook_disabled,
secret_unavailable. Never response text. |
redelivery_of | string (uuid) | null | |
created_at | string (date-time) | |
last_attempt_at | string (date-time) | null | |
next_attempt_at | string (date-time) | null | |
delivered_at | string (date-time) | null |
WebhookDeliveryPageobject
deliveries | WebhookDelivery[] | |
next_cursor | string | null | Opaque; null on the last page. |
WebhookPayloadobject
The body of every delivery (not a response of this API). data is a FeedNotification, or for a
ping an object with message and event_types. When a notification would make the body larger
than 256 KiB, truncated is true and data holds only id, type, created_at and event_id:
read the rest from GET /v1/feed.
type | string | one of restock, price_change, smart_alert, event_drop, queue, shopify, ping |
webhook_id | string (uuid) | |
created_at | string (date-time) | |
truncated optional | boolean | Present (true) only on a truncated notification. |
data | FeedNotification | object | object |