Search docs ⌘K
esc
Type to search across all documentation pages
Sketches

Sketches

Probabilistic analytics primitives for high-volume event streams. HyperLogLog estimates unique counts, and Count-Min Sketch estimates item frequencies without retaining the raw source data.

Approximate by design: Sketches trade exactness for throughput and tiny memory footprints. Use them for rolling analytics and ranking, not for reconstructing exact user lists or payload history.

Add HyperLogLog Elements

POST
/infra/sketches/hll/{key}/add
sketches:write0.0000053 tokens

Add one or more elements to a HyperLogLog sketch for approximate unique counting.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/sketches/hll/{key}/add \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"elements":[]}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.infra.sketches.hll.add('visitors:2026-03-10', ['u_1', 'u_2', 'u_3'])
  1. Open Dashboard → Sketches and select your project
  2. Stay on the HyperLogLog tab and enter the sketch key
  3. Paste newline-separated or JSON-array elements, then click Add elements
Sketches are still key-driven structures, so the dashboard operates on the exact key you choose.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Body field
Type
Description
elements required
array
1–1000 items
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

Estimate HyperLogLog Count

GET
/infra/sketches/hll/{key}/count
sketches:read0.0000008 tokens

Estimate the cardinality of a HyperLogLog sketch.

curl
curl https://api.saasignal.saastemly.com/infra/sketches/hll/{key}/count \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const { count } = await ss.infra.sketches.hll.count('visitors:2026-03-10')
  1. Open Dashboard → Sketches and select your project
  2. Stay on the HyperLogLog tab and enter the sketch key
  3. Click Count to fetch the current approximate unique count
Counts are approximate and reflect the probabilistic nature of HyperLogLog.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

Merge HyperLogLogs

POST
/infra/sketches/hll/merge
sketches:write0.0000053 tokens

Merge multiple HyperLogLog sketches into a destination key.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/sketches/hll/merge \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"dest_key":"...","source_keys":[]}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.infra.sketches.hll.merge('visitors:week-11', [
  'visitors:2026-03-10',
  'visitors:2026-03-11',
])
  1. Open Dashboard → Sketches and select your project
  2. On the HyperLogLog tab, fill in the destination key and source keys
  3. Click Merge to roll multiple sketches into a new aggregate key
For repeatable rollups, move this same flow into Jobs or Workflows after validating it here.
Body field
Type
Description
dest_key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
source_keys required
array
1–100 items
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

Increment Count-Min Sketch

POST
/infra/sketches/cms/{key}/increment
sketches:write0.0000053 tokens

Increment one or more items inside a Count-Min Sketch.

curl
curl -X POST https://api.saasignal.saastemly.com/infra/sketches/cms/{key}/increment \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"elements":[]}'
json — 200 OK
{ "status": "ok" }
typescript
await ss.infra.sketches.cms.increment('errors:daily', [
  { item: '429', count: 1 },
  { item: '500', count: 3 },
])
  1. Open Dashboard → Sketches and select your project
  2. Switch to the Count-Min Sketch tab and enter the sketch key
  3. Paste newline-separated item,count rows or a JSON array, then click Increment
Like Locks, sketches are key-driven, so there is no cross-project browser here.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Body field
Type
Description
elements required
array
1–1000 items
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited

Estimate Count-Min Sketch Frequency

GET
/infra/sketches/cms/{key}/estimate
sketches:read0.0000008 tokens

Estimate the frequency of a single item in a Count-Min Sketch.

curl
curl https://api.saasignal.saastemly.com/infra/sketches/cms/{key}/estimate?item=... \
  -H "Authorization: Bearer sk_live_..."
json — 200 OK
{ "status": "ok" }
typescript
const estimate = await ss.infra.sketches.cms.estimate('errors:daily', '429')
// estimate.estimated_count
  1. Open Dashboard → Sketches and select your project
  2. Switch to the Count-Min Sketch tab and enter both the key and lookup item
  3. Click Estimate to fetch the current approximate frequency
The estimate is an upper bound, so use it for trends and ranking rather than exact source-of-truth counts.
Path param
Type
Description
key required
string
1–512 charspattern ^(?!.*\.\.)[^\x00-\x1f\x7f]+$
Query param
Type
Description
item required
string
1–512 chars
Error responses
401 Unauthorized
402 Insufficient tokens
429 Rate limited