List entity change events

curl --request GET \
  --url https://api.example.com/api/events

{
  "data": [
    {
      "data": {
        "id": "<string>",
        "device_asset_id": "<string>",
        "device_id": "<string>",
        "mime_type": "<string>",
        "original_file_name": "<string>",
        "file_created_at": "2023-11-07T05:31:56Z",
        "file_modified_at": "2023-11-07T05:31:56Z",
        "local_datetime": "2023-11-07T05:31:56Z",
        "checksum": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "checksum_sha1": "<string>",
        "exif": {
          "asset_id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "make": "<string>",
          "model": "<string>",
          "orientation": 123,
          "modified_datetime": "2023-11-07T05:31:56Z",
          "original_datetime": "2023-11-07T05:31:56Z",
          "digitized_datetime": "2023-11-07T05:31:56Z",
          "lens_model": "<string>",
          "f_number": 123,
          "focal_length": 123,
          "iso": 123,
          "exposure_time": 123,
          "exposure_bias": 123,
          "latitude": 123,
          "longitude": 123,
          "altitude": 123,
          "city": "<string>",
          "state": "<string>",
          "country": "<string>",
          "description": "<string>",
          "fps": 123,
          "live_photo_cid": "<string>",
          "projection_type": "<string>",
          "profile_description": "<string>",
          "auto_stack_id": "<string>",
          "rating": 123
        },
        "metrics": {},
        "download_url": "<string>",
        "thumbnail_url": "<string>",
        "faces": [
          {
            "id": "<string>",
            "asset_id": "<string>",
            "bounding_box": {},
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "person_id": "<string>",
            "timestamp_ms": 123,
            "thumbnail_url": "<string>"
          }
        ],
        "people": [
          {
            "id": "<string>",
            "is_hidden": true,
            "is_favorite": true,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "name": "<string>",
            "birth_date": "2023-12-25",
            "thumbnail_face_id": "<string>",
            "thumbnail_face_url": "<string>"
          }
        ],
        "width": 0,
        "height": 0,
        "file_size_bytes": 0
      },
      "entity_type": "asset"
    }
  ]
}

events

List entity change events

Retrieves a list of entity change events for syncing.

Events are returned in order of entity type priority (assets first, then exif, albums, etc.), then by updated_at timestamp (oldest first), then by entity ID for tie-breaking.

Pagination: Use updated_at_gte with the timestamp of the last received event to fetch the next page. When multiple entities share the same timestamp, also provide starting_after_id with the last entity’s ID to avoid duplicates. Use updated_at_lt to bound the sync window and prevent infinite loops when new events are created during sync.

Important: When using starting_after_id, you must specify exactly one entity_types value. This ensures the cursor ID is unambiguous. To sync all entity types with cursor support, query each entity type separately.

Recommended sync pattern (per entity type):

Capture current time as sync_started_at
For each entity type, fetch events with entity_types={type}&updated_at_lt=sync_started_at
For subsequent pages, use entity_types={type}&updated_at_gte={last.updated_at}&starting_after_id={last.id}&updated_at_lt=sync_started_at
Continue until an empty result set is returned
Store sync_started_at as checkpoint for next sync

Entity ID field by type:

Most entities: use the id field from the response
Exif: use the asset_id field (exif has no separate id)

GET

api

events

List entity change events

curl --request GET \
  --url https://api.example.com/api/events

{
  "data": [
    {
      "data": {
        "id": "<string>",
        "device_asset_id": "<string>",
        "device_id": "<string>",
        "mime_type": "<string>",
        "original_file_name": "<string>",
        "file_created_at": "2023-11-07T05:31:56Z",
        "file_modified_at": "2023-11-07T05:31:56Z",
        "local_datetime": "2023-11-07T05:31:56Z",
        "checksum": "<string>",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z",
        "checksum_sha1": "<string>",
        "exif": {
          "asset_id": "<string>",
          "created_at": "2023-11-07T05:31:56Z",
          "updated_at": "2023-11-07T05:31:56Z",
          "make": "<string>",
          "model": "<string>",
          "orientation": 123,
          "modified_datetime": "2023-11-07T05:31:56Z",
          "original_datetime": "2023-11-07T05:31:56Z",
          "digitized_datetime": "2023-11-07T05:31:56Z",
          "lens_model": "<string>",
          "f_number": 123,
          "focal_length": 123,
          "iso": 123,
          "exposure_time": 123,
          "exposure_bias": 123,
          "latitude": 123,
          "longitude": 123,
          "altitude": 123,
          "city": "<string>",
          "state": "<string>",
          "country": "<string>",
          "description": "<string>",
          "fps": 123,
          "live_photo_cid": "<string>",
          "projection_type": "<string>",
          "profile_description": "<string>",
          "auto_stack_id": "<string>",
          "rating": 123
        },
        "metrics": {},
        "download_url": "<string>",
        "thumbnail_url": "<string>",
        "faces": [
          {
            "id": "<string>",
            "asset_id": "<string>",
            "bounding_box": {},
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "person_id": "<string>",
            "timestamp_ms": 123,
            "thumbnail_url": "<string>"
          }
        ],
        "people": [
          {
            "id": "<string>",
            "is_hidden": true,
            "is_favorite": true,
            "created_at": "2023-11-07T05:31:56Z",
            "updated_at": "2023-11-07T05:31:56Z",
            "name": "<string>",
            "birth_date": "2023-12-25",
            "thumbnail_face_id": "<string>",
            "thumbnail_face_url": "<string>"
          }
        ],
        "width": 0,
        "height": 0,
        "file_size_bytes": 0
      },
      "entity_type": "asset"
    }
  ]
}

Query Parameters

library_id

string | null

Library to list events from. If not provided, uses the user's default library.

updated_at_gte

string<date-time> | null

Only return events with updated_at >= this timestamp (ISO 8601 format)

updated_at_lt

string<date-time> | null

Only return events with updated_at < this timestamp (ISO 8601 format). Recommended for bounding sync operations.

starting_after_id

string | null

Entity ID to start after for tie-breaking when paginating. Used with updated_at_gte for composite keyset pagination. Requires exactly one entity_types value. For exif entities, use asset_id.

entity_types

string | null

Comma-separated list of entity types to include (e.g., 'asset,album'). Valid types: asset, album, person, face, album_asset, exif. Default: all types.

limit

integer

default:100

Maximum number of events to return (1-500)

Required range: 1 <= x <= 500

Response

Successful Response

Response containing events.

data

required

List of events, ordered by entity type priority, then updated_at, then entity_id

Event payload for asset entities.

Show child attributes

Remove assets from album

List user's libraries

⌘I

oauth

assets

albums

events

libraries

search

faces

people

api-keys

tasks

users

List entity change events

Query Parameters

Response