Insights and Counters
Set insight values and increment or decrement numeric counters.
Insights and Counters
Insights display a value for a project, such as revenue or queue depth. Open your project and select Insights to view its cards. A card is matched by project ID and title; use the same title when updating it.
Send requests from your server with a secret API key (ev_…). Publishable keys cannot change insights. Get your key from the API page and copy the project ID from the project's URL.
Set a value
Use POST /api/insight to create or replace a card's value:
curl -X POST https://app.getbutters.com/api/insight \
-H "Authorization: Bearer $BUTTERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project":"YOUR_PROJECT_ID","title":"Signups","value":10,"icon":"📈"}' Values can be strings or numbers, including 0 and an empty string. For example, a revenue display can use "$1,200". Use a plain numeric value for cards you intend to increment.
Increment or decrement a counter
Use PATCH /api/insight with a numeric $inc to add to the current value:
curl -X PATCH https://app.getbutters.com/api/insight \
-H "Authorization: Bearer $BUTTERS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"project":"YOUR_PROJECT_ID","title":"Signups","$inc":1}' A negative number subtracts; decimals and zero are accepted. If the card does not exist, $inc becomes its initial value. Existing values must be numeric. Concurrent increments add together without losing updates. Each request adds again, so retrying after a lost response can increment the counter twice.
Both operations return 200 with {"ok":true}. To check the example, set Signups to 10, increment by 1, then reload Insights. The value should be 11. Send $inc: -1 to bring it back to 10.
The optional icon is limited to 16 characters. Omitting it on an update preserves the existing icon.
Troubleshooting
- project, title, and a finite numeric $inc are required (
400): include a project ID, a non-empty title, and a JSON number, such as1, not"1". - Insight value must be numeric to increment (
400): usePOSTto set the card to a numeric value before incrementing it. A value such as"$1,200"cannot be incremented. - icon must be a string (
400): send an emoji as a JSON string. - Invalid API key (
401): check the secret key and Bearer header. - Publishable keys can only send events and identify users (
403): use a secret key from your server. - Project not found (
404): check the project ID and that your key belongs to the project's team.
See API Reference for the full request fields and JavaScript SDK for browser event tracking.