Skip to main content

Overview

The Photo Timeline endpoints let participants discover their photos by when they were captured. Use the days endpoint to render a date / hour picker, then fetch a windowed slice of photos with the images endpoint. Photos are bucketed and queried by the capture timestamp recorded on each image; photos without a timestamp are excluded from both endpoints.
Building a participant-facing gallery or search app? Follow the Participant App guide (coding agents get it in the 9pic-integration skill): call the API only from your backend, save each search ID, check Event Details first, keep one search identifier per search, and show previews rather than originals.
Photo timeline must be enabled for the event. Check the timeline_search flag from Event Details before calling either endpoint.
This endpoint always returns every timestamped photo mapped to the event. It does not honour internal visibility flags such as show_all_images.
Timeline timestamps are the event’s local clock time stored as if it were UTC. A photo taken at 5:00 AM at the venue is stored as 05:00 UTC. Format them with timeZone: 'UTC' and build from and to the same way. Converting to the viewer’s time zone shifts every photo by the viewer’s offset.

Endpoints

Path Parameters

GET /timeline/days — Day and Hour Buckets

Returns per-day and per-hour photo counts for the timeline picker. Days are ordered ascending by date; within each day, hours are ordered ascending by hour. Dates are YYYY-MM-DD and hours are 0–23. They are the event’s local clock time, stored as if it were UTC.

Query Parameters

This endpoint takes no query parameters.

Example Request

Example Response

GET /timeline/images — Windowed Photos

Returns paginated photo objects (large URL, thumbnail URL, image ID, width, height) captured within a [from, to) Unix-epoch-second window, ordered by ascending capture timestamp.

Query Parameters

This endpoint returns paginated results. See the Pagination Model.

Example Request

Example Response

Response Models

original_url is null in the timeline response. Use Download Original Photos with method: "image_ids" to fetch presigned download links for the originals once a participant picks photos from their window.

Error Responses

See Errors for canonical descriptions and retry guidance.