Counters
REST APITypeScriptPythonGoJavaC#PHPRubyRustDartKotlinSwiftZig

Ruby SDK

Unpublished

Pure Ruby, zero dependencies, arbitrary precision via Integer.

Initialize

The API key is a required keyword argument.

example.rb
require "counters"

client = Counters::Client.new(api_key: ENV.fetch("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 a Hash. Amounts accept an Integer or a digit String.

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 Hash
puts c["value"]     # "42"

Read

Read the current value, or a per-bucket time series. Ruby keyword arguments work directly — from: is a legal keyword (unlike Python).

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 counters in the organization.

manage
reg.clear
reg.delete

page = client.list(limit: 50)

Lifecycle

Buffered writes flush on a background timer and at max_batch_size. Call close before exit to flush and stop it.

lifecycle
client.close  # flush + stop the background timer

Errors

Bad keys or amounts raise Counters::ValidationError before any request. Failed requests raise Counters::ApiError (with #status, #title, #problem); both subclass Counters::Error.

errors
begin
  reg.add_now(1)
rescue Counters::ValidationError
  raise                        # bad input
rescue Counters::ApiError => e
  warn "#{e.status} #{e.title}"
end
Prefer raw HTTP? See the REST API reference. Create a key in your dashboard.