Public read API
Read counters, current totals, and recent count events with an organization API key. The API is read-only.
Updated
| Method | Endpoint | Returns |
|---|---|---|
| GET | /api/v1/counters | Every counter and its total |
| GET | /api/v1/counters/:counterId | One counter and its total |
| GET | /api/v1/counters/:counterId/history | Recent count events, newest first |
Authentication
Every request goes to https://api.snapcount.app and carries an organization API key as a Bearer token.
Authorization: Bearer sc_live_...- The public API comes with Pro and Enterprise. On any other plan it returns
403. - Owners and admins create and revoke keys in Settings, Developers. An organization can hold up to 10 keys.
- A key reads only its own organization. Give each integration its own key so you can revoke one without breaking the others.
List counters
GET/api/v1/counters
Returns every counter in the organization with its current total, sorted by name.
curl https://api.snapcount.app/api/v1/counters \
-H "Authorization: Bearer sc_live_..."{
"counters": [
{
"id": "cm1gatea0001",
"name": "Gate A",
"count": 187,
"incrementStep": 1,
"decrementStep": 1,
"mode": "both",
"organizationId": "cm1org0001",
"groupId": null,
"goalTarget": null,
"locked": false,
"version": 212,
"lastEventId": 5812,
"createdAt": "2026-09-20T08:00:00.000Z",
"updatedAt": "2026-09-26T18:42:10.000Z"
}
]
}Counter fields
| Field | Type | Meaning |
|---|---|---|
count | integer | The current total. |
incrementStep | integer | How much one tap on plus adds. |
decrementStep | integer | How much one tap on minus takes away. |
mode | string | both, increment-only, or decrement-only. |
groupId | string or null | The counter group it belongs to, if any. |
goalTarget | number or null | The goal set on the counter, if any. |
locked | boolean | True while an admin has locked the counter. |
lastEventId | integer | Id of the newest count event. It only goes up, so compare it to spot a change. |
updatedAt | date-time | When the counter last changed. |
Get a counter
GET/api/v1/counters/:counterId
Returns one counter in the same shape as an item in the list. A counter that does not exist in the key's organization returns 404.
curl https://api.snapcount.app/api/v1/counters/cm1gatea0001 \
-H "Authorization: Bearer sc_live_..."Counter history
GET/api/v1/counters/:counterId/history
Returns recent count events, newest first. Rows that only changed a counter's settings (update) are left out.
| Parameter | Default | Meaning |
|---|---|---|
limit | 100 | Events to return, from 1 to 500. |
beforeEventId | none | Only events with a lastEventId lower than this. Use it to read the next page. |
curl "https://api.snapcount.app/api/v1/counters/cm1gatea0001/history?limit=50" \
-H "Authorization: Bearer sc_live_..."{
"counterId": "cm1gatea0001",
"counterName": "Gate A",
"events": [
{
"id": "cm1evt5812",
"counterId": "cm1gatea0001",
"eventType": "increment",
"count": 187,
"previousCount": 186,
"delta": 1,
"lastEventId": 5812,
"metadata": null,
"createdAt": "2026-09-26T18:42:10.000Z"
}
]
}Read the next page
Pass the lastEventId of the oldest event you received as beforeEventId. An empty events list means you have reached the start.
curl "https://api.snapcount.app/api/v1/counters/cm1gatea0001/history?limit=50&beforeEventId=5763" \
-H "Authorization: Bearer sc_live_..."Rate limits
Limits count per API key, in two windows. Responses carry standard RateLimit headers so you can slow down before you hit them.
| Plan | Per minute | Per hour |
|---|---|---|
| Pro | 60 | 1,000 |
| Enterprise | 300 | 10,000 |
Errors
Errors come back as JSON with an error message, and a machine-readable code where one applies.
| Status | Code | When |
|---|---|---|
401 | none | The key is missing, revoked, or wrong. |
403 | PLAN_REQUIRED | The organization is not on Pro or Enterprise. |
404 | none | The counter is not in this organization. |
429 | RATE_LIMITED | The key is over its per-minute or per-hour limit. |
{
"error": "The public API requires a Pro plan",
"code": "PLAN_REQUIRED",
"requiredPlan": "organization"
}Was this page helpful?
Ready to connect SnapCount?
Create an API key or a webhook endpoint in Settings. The public API and webhooks come with Pro and Enterprise.