Creating & incrementing counters

To create a new counter or increment an existing counter, include the counter property in the body of a POST to the /events endpoint. More than one counter can be incremented in the same request.

Note: It may take up to 30 seconds after an event has been posted for the counter to be incremented.

Request syntax

curl -X POST<org>/<app>/events -d '{"timestamp":<timestamp>, "counters" : {<counter_name>:<increment_value>}}'


Parameter Description
org Organization UUID or organization name
app Application UUID or application name
timestamp A required UNIX timestamp that specifies the time the counter is being incremented.
counter_name The name of the counter to create or the existing counter to increment.
increment_value The value to increment the counter by.

Regarding the increment_value, a negative number can be specified to decrement the value. A value of ‘0’ can be specified to reset the value of the counter.

For the timestamp, specifying a value of 0 will automatically assign the current time.

Example request

The following request will increment the ‘button_clicks’ counter by one, with a timestamp of the current time.

curl -X POST -d '{"timestamp":0, "counters" : {"button_clicks":1}}'

Example response

  "action" : "post",
  "application" : "f34f4222-a166-11e2-a7f7-02e81adcf3d0",
  "params" : { },
  "path" : "/events",
  "uri" : "",
  "entities" : [ {
    "uuid" : "b11217fc-9d3a-1427-b24e-699740088e05",
    "type" : "event",
    "created" : 1401224590293,
    "modified" : 1401224590293,
    "timestamp" : 1401224590293,
    "counters" : {
      "button_clicks" : 1
    "message" : null,
    "metadata" : {
      "path" : "/events/b11217fc-9d3a-1427-b24e-699740088e05"
  } ],
  "timestamp" : 1401224590291,
  "duration" : 30,
  "organization" : "your-org",
  "applicationName" : "your-app"

Decrementing/resetting counters

To decrement a counter, specify a negative number for the counter value in any of the above examples.

To reset a counter, specify a value of 0 for the counter value in any of the above examples.

Note that the Usergrid JavaScript SDK also provides dedicated methods for decrementing and resetting counters.

Using counters hierarchically

You can organize counters into hierarchies by giving them dot-separated names, e.g. button_clicks.homepage. Incrementing a counter lower in a hierarchy increments all of the counters upward in the hierarchy chain.

For example, you want to log errors that your app generates, so you create hierarchical counters for each module and function within that module. In this example, you create the following set of counters:


Incrementing errors.module.function by 1 increments all three counters by 1. A hierarchy can be a useful way of easily tracking actions in your app at both a cumulative and granular level.