getTimeBucket

getTimeBucket

Query Parameters
albumId uuid Filter assets belonging to a specific album
isFavorite boolean Filter by favorite status (true for favorites only, false for non-favorites only)
isTrashed boolean Filter by trash status (true for trashed assets only, false for non-trashed only)
key string
order string Possible values: [asc, desc] Sort order for assets within time buckets (ASC for oldest first, DESC for newest first)
personId uuid Filter assets containing a specific person (face recognition)
tagId uuid Filter assets with a specific tag
timeBucket string — REQUIRED Time bucket identifier in YYYY-MM-DD format (e.g., "2024-01-01" for January 2024)
userId uuid Filter assets by specific user ID
visibility string Possible values: [archive, timeline, hidden, locked] Filter by asset visibility status (ARCHIVE, TIMELINE, HIDDEN, LOCKED)
withPartners boolean Include assets shared by partners
withStacked boolean Include stacked assets in the response. When true, only primary assets from stacks are returned.

Responses

200 Schema — OPTIONAL city string[] Array of city names extracted from EXIF GPS data country string[] Array of country names extracted from EXIF GPS data duration string[] Array of video durations in HH:MM:SS format (null for images) fileCreatedAt string[] Array of file creation timestamps in UTC (ISO 8601 format, without timezone) id string[] Array of asset IDs in the time bucket isFavorite boolean[] Array indicating whether each asset is favorited isImage boolean[] Array indicating whether each asset is an image (false for videos) isTrashed boolean[] Array indicating whether each asset is in the trash livePhotoVideoId string[] Array of live photo video asset IDs (null for non-live photos) localOffsetHours number[] Array of UTC offset hours at the time each photo was taken. Positive values are east of UTC, negative values are west of UTC. Values may be fractional (e.g., 5.5 for +05:30, -9.75 for -09:45). Applying this offset to 'fileCreatedAt' will give you the time the photo was taken from the photographer's perspective. ownerId string[] Array of owner IDs for each asset projectionType string[] Array of projection types for 360° content (e.g., "EQUIRECTANGULAR", "CUBEFACE", "CYLINDRICAL") ratio number[] Array of aspect ratios (width/height) for each asset stack array[] — OPTIONAL Array of stack information as [stackId, assetCount] tuples (null for non-stacked assets) thumbhash string[] Array of BlurHash strings for generating asset previews (base64 encoded) visibility string[] Possible values: [archive, timeline, hidden, locked] Array of visibility statuses for each asset (e.g., ARCHIVE, TIMELINE, HIDDEN, LOCKED)