Get asset counts

curl --request GET \
  --url https://api.gumnut.ai/api/assets/counts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gumnut.ai/api/assets/counts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gumnut.ai/api/assets/counts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gumnut.ai/api/assets/counts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gumnut.ai/api/assets/counts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "time_bucket": "2023-11-07T05:31:56Z",
      "count": 123
    }
  ],
  "has_more": true
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

assets

Get asset counts

Counts assets bucketed by time period — use this to summarize a library (or a filtered slice) without paging through the full timeline. Returns one row per bucket, newest-first by default or oldest-first when order=asc, with optional filtering by album, album membership, people, rating, media type, date range, location, or trash state.

To list the actual assets within a bucket, call list_assets with the same filters and a local_datetime_after / local_datetime_before window matching the bucket. Does not filter by image content; for content-based search use search_assets.

Pagination: When has_more is true, pass the last time_bucket from data as starting_after_bucket. Repeat the same group_by, order, date bounds, and non-date filters. Count bounds, the cursor, and returned bucket starts are timezone-naive local-calendar values.

GET

api

assets

counts

Get asset counts

curl --request GET \
  --url https://api.gumnut.ai/api/assets/counts \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.gumnut.ai/api/assets/counts', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.gumnut.ai/api/assets/counts",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.gumnut.ai/api/assets/counts"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.gumnut.ai/api/assets/counts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "time_bucket": "2023-11-07T05:31:56Z",
      "count": 123
    }
  ],
  "has_more": true
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

{
  "detail": "<string>"
}

Authorizations

Authorization

string

header

required

Gumnut API key (apikey_...) sent as a Bearer token in the Authorization header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it.

Query Parameters

library_id

string | null

Library to count assets in. Optional if the user has a single live (non-trashed) library; required when they have multiple.

group_by

enum<string>

default:month

Calendar period to use for each count bucket.

Available options:

day,

week,

month,

year

album_id

string | null

Return only assets in this album — the album's album_ ID, not its name.

album_filter

enum<string>

default:all

Filter by album membership in general, rather than by membership of one specific album. This filter is independent of album_id, but combining not_in_album with album_id is contradictory and returns 422. Defaults to all.

Available options:

all,

in_album,

not_in_album

person_id

string | null

deprecated

Deprecated compatibility alias for one person_ids value. Do not combine it with person_ids.

person_ids

string[] | null

Filter to assets containing faces belonging to ALL of these people (intersection, not union). Accepts up to 200 IDs across repeated person_ids= query params or comma-delimited values. Person IDs are carried by the entries of an asset's people field (returned with include=people).

media_type

enum<string> | null

Filter to one media class (image or video). Omit to include both images and videos. Which media class an asset belongs to.

Every image format is image and every video format is video. An asset's class is fixed by the file originally uploaded, so an edited photo is still image.

Available options:

image,

video

ratings

integer[] | null

Return assets whose effective rating is one of these exact values. Values must be integers from 0 through 5; 5 is a favorite. 0 matches every unrated form: an explicit zero, a null or legacy out-of-range effective rating, or an asset with no metadata. Accepts repeated ratings= parameters or one comma-delimited value. Omit the parameter for no rating filter.

Required range: 0 <= x <= 5

local_datetime_after

string<date-time> | null

Only include assets captured strictly after this local wall-clock datetime (ISO 8601; exclusive). Asset counts accept timezone-naive values only; a Z suffix or timezone offset returns 422. Repeat this bound unchanged on every pagination page.

local_datetime_before

string<date-time> | null

Only include assets captured strictly before this local wall-clock datetime (ISO 8601; exclusive). Asset counts accept timezone-naive values only; a Z suffix or timezone offset returns 422. Repeat this bound unchanged on every pagination page.

center

string | null

Center point of a radius location filter: two comma-separated decimal-degree numbers longitude,latitude, e.g. -77.05,38.95. Supply with radius. Mutually exclusive with bbox.

radius

number | null

Radius of the center location filter, in meters (greater than 0, at most 50,000). Supply with center. Mutually exclusive with bbox.

bbox

string | null

Bounding-box (map viewport) location filter: four comma-separated decimal-degree numbers min_longitude,min_latitude,max_longitude,max_latitude (west,south,east,north), e.g. -77.1,38.9,-77.0,39.0. A box whose min_longitude exceeds max_longitude crosses the antimeridian: it selects the band running east from min_longitude over ±180° to max_longitude, so there is no need to split it client-side. Longitude order is therefore significant — transposed corners read as a crossing viewport, not as an error. A viewport 360° or wider must be sent as the full range -180,...,180,..., which the wrapped form cannot express. Mutually exclusive with center/radius.

starting_after_bucket

string<date-time> | null

Cursor for time-bucket pagination. Pass the last returned time_bucket unchanged; buckets after it in the requested order are returned. Omit for the first page.

state

enum<string>

default:live

Which set of assets to count: live (default — excludes trashed assets), trashed (only trashed assets), or all (both live and trashed).

Available options:

live,

trashed,

all

order

enum<string>

default:desc

Sort direction for capture-date buckets: desc returns newest buckets first; asc returns oldest buckets first.

Available options:

asc,

desc

limit

integer

default:20

Maximum number of time buckets to return per page (1–200). Defaults to 20.

Required range: 1 <= x <= 200

Response

Successful Response

data

TimeBucketCount · object[]

required

Time bucket and count pairs in the requested direction

Show child attributes

has_more

boolean

required

True if there are more time buckets. To fetch the next page, pass the last time_bucket as starting_after_bucket. Keep the library scope, group_by, order, state, date bounds, and every population filter unchanged.

oauth

assets

album-assets

albums

events

libraries

search

faces

people

api-keys

server

stacks

tasks

users

Get asset counts

Authorizations

Query Parameters

Response