Skip to main content
GET
List assets in a library

Query Parameters

library_id
string | null

Library to list assets from. Optional if the user has a single library; required when they have multiple.

album_id
string | null

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.

person_id
string | null
deprecated

Deprecated compatibility alias for a single person_ids value.

person_ids
string[] | null

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).

stack_id
string | null

Return only assets belonging to this stack (the asset_stack_ ID carried by the stack_id field on every asset).

ids
string[] | null

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.

local_datetime_after
string<date-time> | null

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.

local_datetime_before
string<date-time> | null

Only include assets captured strictly before this instant (ISO 8601; exclusive). Same conversion requirement and awareness/offset semantics as local_datetime_after.

center
string | null

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
number | null

Radius of the center location filter, in meters (greater than 0, at most 50000).

bbox
string | null

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.

starting_after_id
string | null

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.

state
enum<string>
default:live

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.

Available options:
live,
trashed,
all
order
enum<string>
default:desc

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.

Available options:
asc,
desc
limit
integer
default:20

Maximum number of assets to return per page (1–200). Defaults to 20.

Required range: 1 <= x <= 200
include
string[] | null

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

data
AssetResponse · object[]
required

List of assets

has_more
boolean
required

True if there are more assets after this page. Pass the last asset's id as starting_after_id and repeat the same filters, state, and order to fetch the next page.