Reading totals

Your code can ask Bump for a trackable's totals, like the number of maps exported so far for a line on your homepage. One trackable per request, for the whole project.

#A token that can read

Reading takes a token made with Can read totals on, in Developers > API tokens. It's off by default, and an existing token can't get it later, so make a new one. A token that can read can still send events.

The token decides the environment, like it does for events: a bump_live_ token reads live totals, a bump_test_ token test totals.

#The request

curl "https://api.bumpbunny.dev/v1/trackables?handle=exports.png" \
  -H "Authorization: Bearer bump_test_…"

The handle goes in the query string, not in the path. Handles can contain dots, and a URL ending in .png looks like an image to the web servers and caches along the way.

Bump matches the handle exactly as sent and doesn't lowercase or trim it. Trackable handles only hold lowercase letters, digits, _, . and -, so Exports.png and exports.png with a space at the end both answer 404.

In Laravel, the package does this request with Bump::total('exports.png'). See Laravel package.

#The response

{
  "object": "trackable",
  "handle": "exports.png",
  "count": 3,
  "amount": "0.00",
  "currency": "EUR",
  "last_event_at": "2026-10-18T16:48:55Z"
}

These are the totals the dashboard shows, backfilled events included. Totals per identifiable aren't part of it.

Trackables are shared by live and test. One that has only had test events answers a live token with 0, "0.00" and null.

#Store the number

Read the total on a schedule, for example once a day from a scheduled job, store it, and show the stored number. Never call Bump while rendering a page: every page view would wait on Bump, and a busy page would run into the limit of 600 requests a minute per token.

#Errors

A handle Bump doesn't know:

{
  "error": {
    "type": "invalid_request_error",
    "code": "resource_missing",
    "message": "No trackable with that handle in this project.",
    "param": "handle"
  }
}

A trackable exists from its first event in either environment, or from the first objective on it. All four errors show up in Developers > Problems, since a 404 here is usually a typo in a handle. Errors has the rest, like 401 for a revoked token and 429 for too many requests.