Counters
REST APITypeScriptPythonGoJavaC#PHPRubyRustDartKotlinSwiftZig

Python SDK

Unpublished

Pure stdlib, zero dependencies, arbitrary precision via native int.

Initialize

The API key is the first positional argument. base_url defaults to the production host.

example.py
import os
from counters import CountersClient

client = CountersClient(os.environ["COUNTERS_API_KEY"])

Count

add() and subtract() are buffered and coalesced per counter (flushed as one POST /batch); add_now()/subtract_now() write immediately and return the counter. amount accepts an int or a decimal string — Python's native int is already arbitrary precision.

count
reg = client.counter("registrations")

reg.add(1)          # buffered
reg.add(5)          # coalesced
client.flush()      # one POST /batch

c = reg.add_now(1)  # immediate; returns a dict
print(c["value"])   # "42" — a string

Read

Read the current value, or a per-bucket time series.

read
value = reg.value()["value"]

series = reg.series(**{
    "from": "2026-01-01T00:00:00Z",
    "to": "2026-01-08T00:00:00Z",
    "bucket": "1d",
})

Manage

clear() resets to zero (new epoch, history retained); delete() tombstones the counter; list() pages the organization's counters.

manage
reg.clear()
reg.delete()

page = client.list(limit=50)

Lifecycle

Buffered writes flush on a background thread (on an interval and at max_batch_size). Call close() before exit to flush and stop the thread.

lifecycle
client.close()  # flush + stop the background thread

Errors

Invalid keys or amounts raise CountersValidationError before any request. Failed requests raise CountersError, carrying .status and the RFC 9457 .problem body.

errors
from counters import CountersError, CountersValidationError

try:
    reg.add_now(1)
except CountersValidationError:
    raise            # bad input
except CountersError as e:
    print(e.status, e.problem)
Prefer raw HTTP? See the REST API reference. Create a key in your dashboard.