Skip to content
calternal docs

Get Photos for a day

GET
/api/v1/photos/timeline/days/{day}
curl --request GET \
  --url 'https://example.com/api/v1/photos/timeline/days/example?filter=all' \
  --header 'Authorization: Bearer <token>'

Requires a signed-in User. It returns the item count and a page of tiles for the day. It accepts an offset, page limit, a filter for Videos or Stacks, and repeated tags that require every selected Tag. It returns 400 for an invalid date, tag or limit. Route: /api/v1/photos/timeline/days/{day}. Inputs: day, offset, limit, filter, tag. Safe reads can use bounded retries.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
day
required
string

Query Parameters

Section titled “Query Parameters”
offset
integer
limit
integer
filter

Which timeline groups a read returns. videos keeps groups whose display item is a video; stacks keeps RAW+JPEG pairs, Live Photos and bursts.

string
Allowed values: all videos stacks
tag
Array<string>

Repeat tag to require every selected Tag (#1109, DESIGN §33).

Responses

Section titled “Responses”

200

Section titled “200”
Media typeapplication/json
object
count
required
integer format: int64
day
required
string
tiles
required
Array<object>
object
capture_seconds
required
integer format: int64
group_id
required
string
hash
required
string
height
integer | null format: int64
item_id
required
string
kind
string | null
member_count
required
integer format: int64
mime
required
string
name
required
string
path
required

The display item’s Files path as the viewer addresses it: Home relative, or Shared/<owner>/… for a shared library root.

string
thumbhash
string | null
thumbnail_url
required
string
width

Display size after EXIF orientation. Absent when the file does not say; the client then keeps a neutral aspect ratio.

integer | null format: int64
Examplegenerated
{
  "count": 1,
  "day": "example",
  "tiles": [
    {
      "capture_seconds": 1,
      "group_id": "example",
      "hash": "example",
      "height": 1,
      "item_id": "example",
      "kind": "example",
      "member_count": 1,
      "mime": "example",
      "name": "example",
      "path": "example",
      "thumbhash": "example",
      "thumbnail_url": "example",
      "width": 1
    }
  ]
}

400

Section titled “400”
Media typeapplication/json

The standard API error response: { "error": { ... } }.

object
error
required

Error details.

object
code
required

Stable machine-readable code.

string
Allowed values: bad_request unauthorized forbidden not_found conflict name_conflict_case name_too_long push_endpoint_rejected too_many_requests internal service_unavailable
details
One of:

Optional field or operation details.

object
key
additional properties
string
message
required

Safe text for logs or a user-facing error message.

string
Example
{
  "error": {
    "code": "bad_request"
  }
}