Skip to main content
Most list endpoints in the Gumnut API support pagination, filtering, and sorting to help you efficiently retrieve the data you need.

​
Pagination

List endpoints support cursor-based pagination using limit and starting_after_id: 
# Get first 50 assets
GET /api/assets?limit=50

# Get next page, starting after the last asset ID from the previous response
GET /api/assets?limit=50&starting_after_id=asset_abc123
Paginated responses include a has_more field indicating whether additional results exist: 
{
  "data": [
    { "id": "asset_abc123", "type": "IMAGE", ... },
    { "id": "asset_def456", "type": "IMAGE", ... }
  ],
  "has_more": true
}
To fetch the next page, pass the id of the last item as starting_after_id.
If you’re using one of our SDKs, pagination is handled automatically with built-in iterators.

​
Filtering

Use query parameters to filter results: 
# Filter by date range
GET /api/assets?local_datetime_after=2024-01-01T00:00:00&local_datetime_before=2024-02-01T00:00:00

# Filter by library
GET /api/assets?library_id=lib_123

# Filter by album or person
GET /api/assets?album_id=album_456
GET /api/assets?person_id=person_789

​
Filtering by capture time

local_datetime_after and local_datetime_before filter on the asset’s capture time:
  • Send offsetless values such as 2024-01-01T00:00:00 when you want wall-clock filtering.
  • Send offset-aware values such as 2024-01-01T00:00:00-05:00 when you want an absolute time window.
  • Keep both bounds consistent. Mixing an offsetless value with an offset-aware value in the same request is rejected.
  • Assets with a known capture offset are compared using that offset. Assets without one fall back to wall-clock comparison, so offsetless captures still participate in aware range filters.
# Filter by an absolute window in US Eastern time
GET /api/assets?local_datetime_after=2024-01-01T00:00:00-05:00&local_datetime_before=2024-02-01T00:00:00-05:00
See Requests & Responses for how local_datetime is serialized, and see the API Reference tab for the full list of available filter parameters for each endpoint.