Sign in
Timeline

Get time bucket

Changed on

Retrieve a string of all asset ids in a given time bucket.

get/timeline/bucket

Request

  • Base URL: /api (relative, and the document was published on a file host, not at the API’s origin)
  • URL: /api/timeline/bucket
  • Auth: one of:
    • HTTP bearer
    • API key in cookie immich_access_token
    • API key in header x-api-key

Query parameters

albumIdstring uuid

Filter assets belonging to a specific album

bboxstring
Example:11.075683,49.416711,11.117589,49.454875

Bounding box coordinates as west,south,east,north (WGS84)

isFavoriteboolean

Filter by favorite status (true for favorites only, false for non-favorites only)

isTrashedboolean

Filter by trash status (true for trashed assets only, false for non-trashed only)

keystring
order'asc' | 'desc'

Asset sort order

Sort order for assets within time buckets (ASC for oldest first, DESC for newest first)

orderBy'takenAt' | 'createdAt'

Asset sorting property

Date to group and order assets by (takenAt for date taken, createdAt for date added to Immich)

personIdstring uuid

Filter assets containing a specific person (face recognition)

slugstring
tagIdstring uuid

Filter assets with a specific tag

timeBucketstring required
Example:2024-01-01

Time bucket identifier in YYYY-MM-DD format

userIdstring uuid

Filter assets by specific user ID

visibility'archive' | 'timeline' | 'hidden' | 'locked'

Asset visibility

Filter by asset visibility status (ARCHIVE, TIMELINE, HIDDEN, LOCKED)

withCoordinatesboolean

Include location data in the response

withPartnersboolean

Include assets shared by partners

withStackedboolean

Include stacked assets in the response. When true, only primary assets from stacks are returned.

Response

citystring[]

Array of city names extracted from EXIF GPS data

countrystring[]

Array of country names extracted from EXIF GPS data

createdAtstring[] required

Array of UTC timestamps when each asset was originally uploaded to Immich

durationinteger[] required

Array of video/gif durations in milliseconds (null for static images)

fileCreatedAtstring[] required

Array of file creation timestamps in UTC

idstring[] required

Array of asset IDs in the time bucket

isFavoriteboolean[] required

Array indicating whether each asset is favorited

isImageboolean[] required

Array indicating whether each asset is an image (false for videos)

isTrashedboolean[] required

Array indicating whether each asset is in the trash

latitudenumber[]

Array of latitude coordinates extracted from EXIF GPS data

livePhotoVideoIdstring[] required

Array of live photo video asset IDs (null for non-live photos)

localOffsetHoursnumber[] required

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.

longitudenumber[]

Array of longitude coordinates extracted from EXIF GPS data

ownerIdstring[] required

Array of owner IDs for each asset

projectionTypestring[] required

Array of projection types for 360° content (e.g., "EQUIRECTANGULAR", "CUBEFACE", "CYLINDRICAL")

rationumber[] required

Array of aspect ratios (width/height) for each asset

thumbhashstring[] required

Array of BlurHash strings for generating asset previews (base64 encoded)

visibilityAssetVisibility[] required

Array of visibility statuses for each asset (e.g., ARCHIVE, TIMELINE, HIDDEN, LOCKED)

Changes

  • 4c0e6b22daf6Revision changes
    • breaking

      the response property became optional for the status

    • breaking

      the response property became optional for the status

  • 0cca76cd420dRevision changes
    • info

      added the new optional query request parameter orderBy

    • info

      added the required property to the response with the status