Skip to docs content
Browse documentation
On this page

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 as 1, not "1".
  • Insight value must be numeric to increment (400): use POST to 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.