List assets in a library
Returns a paginated list of assets ordered by local capture time (or trash time for trashed assets), newest first by default, optionally filtered by album, person, date range, geographic area, or asset ID. Use this tool for structured browsing and filtering — when the request can be expressed as exact filters on album membership, people, date range, geographic coordinates, or specific asset IDs.
Location filtering is by coordinate: pass a radius (center + radius) or a bounding box (bbox) to restrict results to a geographic area. The two modes are mutually exclusive. To count or cluster geotagged assets across a map viewport (how many photos fall in each area) rather than list them, use get_geo_clusters.
Album and person filters compose using AND; do not supply both person_id and person_ids.
Use search_assets instead when the request involves natural-language image content ('photos of sunsets', 'pictures with my dog'), a place name ('photos from Japan'), or any concept requiring semantic understanding of what's in the image. list_assets filters by coordinate but not by image content, place name, or caption text.
To present a curated set of specific assets to the user (e.g., a hand-picked subset of search_assets results), call this tool with ids=[...] rather than building a custom gallery — the asset IDs you already have are enough to re-render them through the interactive widget.
Pagination is cursor-based: while has_more is true, keep fetching with starting_after_id.
Query parameters
Library to list assets from. Optional if the user has a single library; required when they have multiple.
Library to list assets from. Optional if the user has a single library; required when they have multiple.
Return only assets in this album — the album's album_ ID, not its name. To browse one album's full asset metadata, prefer this filter over list_album_assets, which returns link records.
Return only assets in this album — the album's album_ ID, not its name. To browse one album's full asset metadata, prefer this filter over list_album_assets, which returns link records.
Deprecated compatibility alias for a single person_ids value.
Deprecated compatibility alias for a single person_ids value.
Return only assets containing faces belonging to ALL of these people (intersection, not union). Accepts up to 200 IDs across repeated person_ids= query params or comma-delimited values. Person IDs are carried by the entries of an asset's people field (returned with include=people).
Return only assets containing faces belonging to ALL of these people (intersection, not union). Accepts up to 200 IDs across repeated person_ids= query params or comma-delimited values. Person IDs are carried by the entries of an asset's people field (returned with include=people).
Return only assets belonging to this stack (the asset_stack_ ID carried by the stack_id field on every asset).
Return only assets belonging to this stack (the asset_stack_ ID carried by the stack_id field on every asset).
Look up specific assets by ID (max 200; each ID has the asset_ prefix). Accepts multiple ids= query params or a single comma-delimited value (e.g., ids=asset_1,asset_2). Combines with other filters (album_id, person_ids, stack_id, datetime range) using AND logic — the result is the intersection.
Look up specific assets by ID (max 200; each ID has the asset_ prefix). Accepts multiple ids= query params or a single comma-delimited value (e.g., ids=asset_1,asset_2). Combines with other filters (album_id, person_ids, stack_id, datetime range) using AND logic — the result is the intersection.
Only include assets captured strictly after this instant (ISO 8601; exclusive). Convert a relative or natural-language date phrase ('in 2023') into an explicit bound before sending. local_datetime is the photo's wall-clock time in the device's own timezone. Naive values compare directly against local_datetime. Timezone-aware values: assets with a known offset are compared in UTC (local_datetime - offset); assets without an offset fall back to wall-clock comparison against local_datetime.
Only include assets captured strictly after this instant (ISO 8601; exclusive). Convert a relative or natural-language date phrase ('in 2023') into an explicit bound before sending. local_datetime is the photo's wall-clock time in the device's own timezone. Naive values compare directly against local_datetime. Timezone-aware values: assets with a known offset are compared in UTC (local_datetime - offset); assets without an offset fall back to wall-clock comparison against local_datetime.
Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as local_datetime_after.
Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as local_datetime_after.
Center point of a radius location filter: two comma-separated decimal-degree numbers longitude,latitude, e.g. -77.05,38.95. Supply with radius. Mutually exclusive with bbox.
Center point of a radius location filter: two comma-separated decimal-degree numbers longitude,latitude, e.g. -77.05,38.95. Supply with radius. Mutually exclusive with bbox.
Radius of the center location filter, in meters (greater than 0, at most 50000).
Radius of the center location filter, in meters (greater than 0, at most 50000).
Bounding-box (map viewport) location filter: four comma-separated decimal-degree numbers min_longitude,min_latitude,max_longitude,max_latitude (west,south,east,north), e.g. -77.1,38.9,-77.0,39.0. A box whose min_longitude exceeds max_longitude crosses the antimeridian: it selects the band running east from min_longitude over ±180° to max_longitude, so there is no need to split it client-side. Longitude order is therefore significant — transposed corners read as a crossing viewport, not as an error. A viewport 360° or wider must be sent as the full range -180,...,180,..., which the wrapped form cannot express. Mutually exclusive with center/radius.
Bounding-box (map viewport) location filter: four comma-separated decimal-degree numbers min_longitude,min_latitude,max_longitude,max_latitude (west,south,east,north), e.g. -77.1,38.9,-77.0,39.0. A box whose min_longitude exceeds max_longitude crosses the antimeridian: it selects the band running east from min_longitude over ±180° to max_longitude, so there is no need to split it client-side. Longitude order is therefore significant — transposed corners read as a crossing viewport, not as an error. A viewport 360° or wider must be sent as the full range -180,...,180,..., which the wrapped form cannot express. Mutually exclusive with center/radius.
Cursor for pagination. Pass the id of the last asset in the previous response's data to fetch the next page. Repeat the same filters, state, and order on every page. Omit for the first page. list_assets cursors because it walks a stable capture-time ordering; the sibling search_assets ranks by relevance and so pages by number instead.
Cursor for pagination. Pass the id of the last asset in the previous response's data to fetch the next page. Repeat the same filters, state, and order on every page. Omit for the first page. list_assets cursors because it walks a stable capture-time ordering; the sibling search_assets ranks by relevance and so pages by number instead.
Which set of assets to read from: live (default — only assets that are not trashed), trashed (only trashed assets, ordered by trash time), or all (both live and trashed, ordered by capture time like live). Ordering defaults to newest or most recently trashed first.
Which set of assets to read from: live (default — only assets that are not trashed), trashed (only trashed assets, ordered by trash time), or all (both live and trashed, ordered by capture time like live). Ordering defaults to newest or most recently trashed first.
Sort direction for the selected state's timestamp: capture time for live/all, or trash time for trashed. The asset ID tie-breaker uses the same direction.
Sort direction for the selected state's timestamp: capture time for live/all, or trash time for trashed. The asset ID tie-breaker uses the same direction.
Maximum number of assets to return per page (1–200). Defaults to 20.
Maximum number of assets to return per page (1–200). Defaults to 20.
Opt-in expansion fields. Supported values: metadata (camera/EXIF/GPS and location names), faces, people, metrics (ML quality scores), file_data (a group token populating the nested file_data object with the file/provenance scalars device_asset_id, device_id, file_created_at, file_modified_at, checksum, checksum_sha1, file_size_bytes), and variants (the non-thumbnail asset_urls size variants; without it asset_urls carries only its lean rung — thumbnail, or thumbnail_image for a video with an extracted still, or original for a still-less video — so callers that render non-thumbnail variants must pass it). Accepts multiple include= query params or a single comma-delimited value (e.g. include=faces,people). Unknown values return 422. When omitted, only the lean core is returned (id, mime_type, local_datetime, dimensions, description, thumbhash, asset_urls) and each data field above is null/absent until you request it.
Opt-in expansion fields. Supported values: metadata (camera/EXIF/GPS and location names), faces, people, metrics (ML quality scores), file_data (a group token populating the nested file_data object with the file/provenance scalars device_asset_id, device_id, file_created_at, file_modified_at, checksum, checksum_sha1, file_size_bytes), and variants (the non-thumbnail asset_urls size variants; without it asset_urls carries only its lean rung — thumbnail, or thumbnail_image for a video with an extracted still, or original for a still-less video — so callers that render non-thumbnail variants must pass it). Accepts multiple include= query params or a single comma-delimited value (e.g. include=faces,people). Unknown values return 422. When omitted, only the lean core is returned (id, mime_type, local_datetime, dimensions, description, thumbhash, asset_urls) and each data field above is null/absent until you request it.
Response
Successful Response