Stream entity change events
Returns a paginated stream of change events (create/update/delete) for entities in the library. Each event is a lightweight record — entity_type, entity_id, event_type, and timestamps — pointing at a concrete entity that has changed. Follow up with get_asset, get_album, get_person, or get_face to fetch full entity data when needed.
Use this tool when the user wants to synchronise a local copy of their library, audit recent activity, or detect deletions. Don't use it for content queries — use search_assets or list_assets instead. Events cannot be filtered by content or asset metadata.
Pagination: cursor-based via after_cursor. When has_more is true, pass the last event's cursor value into after_cursor to fetch the next page.
Recommended sync pattern:
- Capture current time as sync_end.
- Fetch events with created_at_lt=sync_end.
- For subsequent pages, use after_cursor={last.cursor}&created_at_lt=sync_end.
- Continue until has_more=false.
- For each event, fetch the entity data from the appropriate endpoint if needed.
- Store sync_end as checkpoint for next sync.
Handling deletions: when event_type ends with _deleted or _removed, the entity no longer exists — remove it from the local cache. Some deletion events include a payload field with context (e.g., album_asset_removed carries album_id and asset_id since the junction row is gone).
Event types:
- asset_created, asset_updated, asset_deleted
- album_created, album_updated, album_deleted
- person_created, person_updated, person_deleted
- face_created, face_updated, face_deleted
- album_asset_added, album_asset_removed
- metadata_updated
Query parameters
Library to stream events from. Optional if the user has a single library; required when they have multiple.
Library to stream events from. Optional if the user has a single library; required when they have multiple.
Opaque cursor from the last event of the previous page. Pass the cursor field from the last event to fetch the next page. Omit for the first page.
Opaque cursor from the last event of the previous page. Pass the cursor field from the last event to fetch the next page. Omit for the first page.
Only return events created at or after this timestamp (ISO 8601). Set this to the previous sync's checkpoint when doing incremental sync.
Only return events created at or after this timestamp (ISO 8601). Set this to the previous sync's checkpoint when doing incremental sync.
Only return events created strictly before this timestamp (ISO 8601). Recommended for bounding a sync operation — capture now once and reuse it as created_at_lt across all pages so newly arriving events don't shift the window.
Only return events created strictly before this timestamp (ISO 8601). Recommended for bounding a sync operation — capture now once and reuse it as created_at_lt across all pages so newly arriving events don't shift the window.
Entity types to include (e.g., asset, album). Valid values: asset, album, person, face, album_asset, metadata. Accepts multiple entity_types= query params or a single comma-delimited value (e.g., entity_types=asset,album). Omit to receive events for all types.
Entity types to include (e.g., asset, album). Valid values: asset, album, person, face, album_asset, metadata. Accepts multiple entity_types= query params or a single comma-delimited value (e.g., entity_types=asset,album). Omit to receive events for all types.
Maximum number of events to return per page (1–200). Defaults to 20.
Maximum number of events to return per page (1–200). Defaults to 20.
Response
Successful Response