Deleted Items
What a tombstone is
A tombstone is the same envelope as a normal feed row, stripped down to the bare identifying fields plus a removal marker. It tells a long-lived mirror that an identifier it cached has left the catalog — hard-deleted, soft-deleted (“trashed”), or merged into another record — so you can drop or redirect the row. Removals ride the same delta loop you already run for updates: there is no second endpoint and no second watermark.
Do not confuse the two status families: eventStatus describes the schedule of a live event, while deletionStatus appears only on a tombstone after a record has left the catalog.
When they appear
Only on delta polls — never on catalog browsing.
Tombstones require dateModifiedFrom
dateModifiedFrom. Queries without it (catalog browsing) never return tombstones — they would just be noise. A tombstone’s dateModified is when the removal became visible on the feed (normally the moment it happened; if we ever publish one late, it carries the later publish time), so the same watermark that catches updates catches the removal. deletedAt is the true removal time, in UTC.What changed on 2026-11-16
On 2026-11-16 removal rows started coming from the JamBase catalog itself. If your code sends dateModifiedFrom, these points apply to you.
deletedAt is now the true removal time in UTC. Removal rows built by our API gateway before 2026-11-16 carried a deletedAt 7 to 8 hours early, because Pacific time was read as UTC, so a sync point you set from an old deletedAt value may shift.
Removal rows can repeat; applying one twice is harmless.
Removal dates have no milliseconds, for example 2026-04-12T18:01:00Z.
If you look up records by ID: a removed event, artist or venue looked up by its JamBase ID now returns 200 with its removal row instead of 400 identifier_invalid. If your code treats every successful lookup as a live record, check for deletionStatus first. See looking up a removed record.
The removals object
A dateModifiedFrom response also carries a top-level removals object that says which removal rows the response covers.
| Field | Meaning |
|---|---|
availableFrom | The oldest sync point for which removal rows are still kept. |
complete | true when the response can include every removal since your dateModifiedFrom. |
scope | all: every removal in the window. matched: only the removals that match your filter. none: this request carries no removal rows. |
When complete is false, your sync point is older than availableFrom, so some removals may be missing. Deleted and trashed rows are kept for 90 days; merges are kept for ever. Re-check your cached identifiers with a lookup by ID or rebuild your cache.
Filtered deltas
A dateModifiedFrom request on /v3/events filtered by artistId or venueId carries only the removal rows that match the filter, and removals.scope is matched. totalItems and totalPages count live rows plus the matching removal rows.
Name and event ID filters carry no removal rows: deltas filtered by artistName, venueName, name or eventId, and ID filters on /v3/artists and /v3/venues, return removals.scope none. To be sure you see every removal, run one unfiltered dateModifiedFrom sweep alongside your filtered loops (geo and date filters still carry all removal rows), or re-check cached identifiers with a lookup by ID.
eventStatus values
The scheduling state of a live event. Keep the row and update its presentation.
| Value | Meaning | Recommended handling |
|---|---|---|
scheduled | The event is expected to happen at its current start date. | Show it normally. |
postponed | The event is delayed and a replacement date is not yet confirmed. | Keep it, label it postponed, and avoid promising the current date. |
rescheduled | The event has moved to a confirmed new date. previousStartDate may contain the prior date. | Keep it and update users from the old date to the new one. |
cancelled | The event will not take place as scheduled, but it remains a live catalog row. | Keep it for history and joins; hide it or clearly label it in upcoming views. |
All four values arrive on normal rows and can change in later delta polls. Always persist eventStatus on upsert. None of these values is a tombstone discriminator.
deletionStatus values
A single discriminator carries the removal class. Live rows omit the field entirely.
| Value | Meaning | Extra fields | What to do |
|---|---|---|---|
deleted | Hard-deleted upstream. The identifier is gone and will not be re-used. | deletedAt | Drop the row from your cache. |
trashed | Soft-deleted upstream. This class is emitted for events only and is not an eventStatus value. | deletedAt | Treat the same as deleted and drop it. A restored show keeps arriving as a removal row until it is back in the catalog, then returns as a normal live row. |
merged | Folded into another record. This row’s identifier is the loser; mergedInto is the survivor. | deletedAt, mergedInto | Repoint cached references to mergedInto. |
mergedInto is the next-hop survivor only. If a survivor later merges again, that produces another tombstone pointing at the next survivor — walk merges as they arrive across delta windows.
Wire shape
A single delta page can mix live rows and tombstones.
A page from GET /v3/events?dateModifiedFrom=2026-04-12T00:00:00Z can include live rows and any supported tombstone class together. Tombstone rows carry only @type, identifier, deletionStatus, deletedAt, dateModified, and (on merged) mergedInto — everything else is omitted.
{"success": { "code": 200 },"pagination": {"page": 1, "perPage": 40, "totalItems": 4, "totalPages": 1,"nextPage": null, "previousPage": null},"events": [{"@type": "Concert","identifier": "jambase:16100021","name": "Phish at Madison Square Garden","eventStatus": "scheduled","dateModified": "2026-04-12T17:34:00Z"},{"@type": "Concert","identifier": "jambase:16223890","deletionStatus": "trashed","deletedAt": "2026-08-19T18:01:00Z","dateModified": "2026-08-22T14:25:00Z"},{"@type": "Concert","identifier": "jambase:16223891","deletionStatus": "deleted","deletedAt": "2026-04-12T18:01:00Z","dateModified": "2026-04-12T18:01:00Z"},{"@type": "Concert","identifier": "jambase:15479255","deletionStatus": "merged","deletedAt": "2026-04-12T19:22:00Z","mergedInto": "jambase:5632389","dateModified": "2026-04-12T19:22:00Z"}]}
Handling tombstones
Branch on deletionStatus inside your existing upsert loop.
Because tombstones arrive on the same response as live rows, you handle them on the same code path — just switch on deletionStatus before upserting:
for (const row of response.events) {switch (row.deletionStatus) {case "deleted":case "trashed":db.events.delete(row.identifier); // drop from your cachebreak;case "merged":db.events.repoint(row.identifier, row.mergedInto); // redirect referencesbreak;default:db.events.upsert(row.identifier, row); // live row — normal upsert}}
Cancellations are not deletes
eventStatus="cancelled" and a bumped dateModified — it is never a tombstone. Handle eventStatus on every upsert; see Bulk Ingest & Delta Sync.Per-feed coverage
Current source coverage, not hypothetical schema capability.
| Feed | @type | Currently sourced deletionStatus values |
|---|---|---|
/v3/events | Concert, Festival | deleted, trashed, merged |
/v3/artists | MusicGroup | deleted, merged |
/v3/venues | Venue | deleted, merged |
/v3/streams | Stream | None. Stream tombstones are not currently sourced or emitted. |
Festival removals arrive on /v3/events with @type Festival, next to concert removals. /v3/festivals and the festival series routes carry no removal rows. Venue removal rows say Venue, the same type as live venue rows (they used to say MusicVenue), and so do venue locations on festival series editions. Other venue objects, such as event locations, use the same value, so you can handle venue objects the same way whether they are live or removed. /v3/streams currently emits no tombstones. Look up previously cached streams by ID instead (a removed stream answers 400 identifier_invalid).
Pagination & retention
Tombstones page like any other row, and the window is bounded.
- They count toward paging. Tombstones count against
perPageandpagination.totalItemsin one combined total, after the live rows. AperPage=100page may be any mix of live rows and tombstones. Artist- and venue-filtered deltas count only the tombstones that match the filter. - Retention is 90 days.
deletedandtrashedtombstones are kept for 90 days, then disappear from the feed.mergedtombstones never expire, because merge collisions in a long-running cache are worse than a stale delete. This window applies to the delta feeds only; a lookup by ID has no time limit. - Two timestamps.
dateModifiedis when the removal became visible on the feed, the value your watermark matches.deletedAtis the true removal time in UTC and can be earlier. - No historical-access tier needed. Tombstones ride the standard
dateModifiedFromloop and reveal only that an identifier left the catalog. Subscriptions limited to upcoming events get them too. On/v3/eventstheir removal rows cover shows dated today or later, so a removed show with an earlier date does not appear. Their artist and venue removal rows are not limited by date.
Looking up a removed record
Check one cached identifier at a time, with or without tombstones.
Look up a stored JamBase ID with GET /v3/events/id/jambase:{id} (or the matching artists or venues lookup). If the record was removed, the response is 200 with its removal row in place of the record, for example { "success": true, "event": { "identifier": "jambase:123", "deletionStatus": "deleted", ... } }. The row has the same fields as a tombstone on the feed. Check for deletionStatus before you treat a lookup result as a live record: drop the cached row for deleted or trashed, and repoint it to mergedInto for merged.
Lookups have no time limit. A deleted or trashed record answers with its removal row however long ago it was removed, just as a merged record does. The 90-day window applies to the delta feeds, not to lookups. Subscriptions limited to upcoming events get the same answer.
The lookup answers 400 with error code identifier_invalid instead for lookups by another source's ID (for example a Ticketmaster ID) and for stream lookups. Treat that answer on a previously cached identifier as removed.
If removal rows cannot be read, the delta request fails, normally with HTTP 503, error code removals_unavailable and a Retry-After header. You never get live rows without their removal rows.
Wait as long as Retry-After says, then retry the same page with the same dateModifiedFrom. Do not advance your watermark past a failed page.
Related
- Bulk Ingest & Delta Sync — the delta loop tombstones ride on
- Search — keyword search across events, artists, and venues
- Pagination — iterating through delta pages
- API Reference — full schema including the tombstone fields