Synchronous Dashboard Counts API

Synchronous Dashboard Counts API

Counts API can be used to programmatically retrieve dashboard counts for events, profiles, properties, trends, and real-time stats.

All endpoints in this section are synchronous i.e. they make blocking calls till the query completes processing. The use case for this is building your own custom dashboard or app on top of the API. For all other use cases such as warehousing/automated reporting etc, it is advisable to use the async version of this API.

Event Counts API

This endpoint is used to retrieve counts for a particular event in a specified duration (along with optional filters).

Request & Response

With your request you will specify a JSON formatted query for records as POST payload along with your CleverTap Account ID and CleverTap Account Passcode in the request headers.

The response to this request will be a JSON object containing status (success/fail). count (count of events for the specified query) will be present if status is success, else the JSON response will contain an error string.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Endpoint

The request to get event counts is an HTTP URL of the following form:

POST https://dashboard.clevertap.com/api/counts/events

Payload

JSON formatted request with the following parameters

Required Parameters

event_name – The name of the event which has been performed by the users whose events you want to download

from & to – Date range within which users should have performed the event you have specified in event_name, input values have to be formatted as integers in format YYYYMMDD

Optional Parameters

Refer here for documentation on advanced queries, their structure, and examples.

Example Payload

{
    "event_name": "choseNewFavoriteFood",
    "event_properties": [
        {
            "name": "value",
            "operator": "contains",
            "value": "piz"
        }
    ],
    "from": 20150810,
    "to": 20151025
}
copy Copied

Response

{
  "status": "success",
  "count": 7138
}
copy Copied

Profile Counts API

This endpoint is used to retrieve count of profiles qualifying for a specific query.

Request & Response

With your request you will specify a JSON formatted query for records as POST payload along with your CleverTap Account ID and CleverTap Account Passcode in the request headers.

The response to this request will be a JSON object containing status (success/fail). count (count of events for the specified query) will be present if status is success, else the JSON response will contain an error string.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Endpoint

The request to get event counts is an HTTP URL of the following form:

POST https://dashboard.clevertap.com/api/counts/profiles

Payload

JSON formatted request with the following parameters

Required Parameters

No mandatory parameters. An empty payload ({}) will return count of all profiles.

Optional Parameters

event_name – The name of the event which has been performed by the users whose events you want to download

from & to – Date range within which users should have performed the event you have specified in event_name, input values have to be formatted as integers in format YYYYMMDD

Refer here for documentation on advanced queries, their structure, and examples.

Example Payload

{
    "event_name": "choseNewFavoriteFood",
    "event_properties": [
        {
            "name": "value",
            "operator": "contains",
            "value": "piz"
        }
    ],
    "from": 20150810,
    "to": 20151025
}
copy Copied

Response

{
  "status": "success",
  "count": 7138
}
copy Copied

Real-time Counts API

This endpoint can be used to retrieve real-time count of active users (last 5 minutes), along with split by user_type, session_source, browser, os, device for active and new users if required.

Request & Response

With your request you can optionally specify certain parameters within JSON body to retrieve counts (split by specified parameter type) along with your CleverTap Account ID and CleverTap Account Passcode in the request headers.

The response to this request will be a JSON object containing status (success/fail).
In case of a successful response:
count will contain the count of active users in real-time
last_processed_ts will be the UNIX epoch timestamp of last processed event in the account

Other response objects are subject to request parameters and are detailed later.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json if payload is present.

Endpoint

The request to get event counts is an HTTP URL of the following form:

POST https://dashboard.clevertap.com/api/counts/now

Payload

JSON formatted request with the following parameters

Required Parameters

No mandatory parameters. An empty payload ({}) will return real-time count of active users.

Optional Parameters

user_type – Boolean. If set to true, will return the split of users by type. Can be new, repeat, addressable or customer.

session_source – Boolean. If set to true, will return the split of users by session source. Can be direct, search, social, others or unavailable.

browser – Boolean. If set to true, will return the split of users by browser.

os – Boolean. If set to true, will return the split of users by OS.

device – Boolean. If set to true, will return the split of users by device type. Can be desktop, mobile, or tablet.

new – Boolean. Can be used along with some of the above (session_source, browser, os, device) to additionally obtain split of new users.

Example Payload

All parameters are optional.

{
	"user_type": true,
	"session_source": true,
	"browser": true,
	"os": true,
	"device": true,
	"new": true
}
copy Copied

Response

If no payload is provided, the response contains only the real-time count of active users.

{
  "status": "success",
  "count": 214,
  "last_processed_ts": 1486536600
}
copy Copied

Here is a sample response with all parameters set to true.

{
  "status": "success",
  "count": 214,
  "user_type": {
    "new": 58,
    "repeat": 25,
    "addressable": 38,
    "customer": 93
  },
  "session_source": {
    "direct": 122,
    "others": 115,
    "search": 18,
    "social": 2,
    "email": 1,
    "unavailable": 4
  },
  "browser": {
    "others": 4,
    "firefox": 2,
    "chrome": 52,
    "ie": 3,
    "mobileapp": 201
  },
  "os": {
    "others": 2,
    "android": 196,
    "ios": 35,
    "windows": 25,
    "mac": 3,
    "linux": 2
  },
  "device": {
    "desktop": 32,
    "mobile": 230,
    "tablet": 1
  },
  "new": {
    "session_source": {
      "direct": 18,
      "others": 50,
      "search": 12,
      "social": 2,
      "email": 1,
      "unavailable": 3
    },
    "browser": {
      "others": 1,
      "firefox": 0,
      "chrome": 36,
      "ie": 3,
      "mobileapp": 47
    },
    "os": {
      "others": 0,
      "android": 67,
      "ios": 2,
      "windows": 15,
      "mac": 2,
      "linux": 1
    },
    "device": {
      "desktop": 18,
      "mobile": 68,
      "tablet": 1
    }
  },
  "last_processed_ts": 1486536600
}
copy Copied

Top Property Counts API

This endpoint is used to retrieve counts for most/least frequently occurring properties for a particular event in a specified duration (along with optional filters).

Request & Response

With your request, you will specify a JSON formatted query for counts as POST payload along with your CleverTap Account ID and CleverTap Account Passcode in the request headers.

The response to this request will be a JSON object containing status (success/fail).
A successful response will return counts of top properties. This is detailed later.
If status is fail, the JSON response will contain an error string.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Endpoint

The request to get top property counts is an HTTP URL of the following form:

POST https://dashboard.clevertap.com/api/counts/top

Payload

JSON formatted request with the following parameters

Required Parameters

event_name – The name of the event which has been performed by the users whose events you want to download

from & to – Date range within which users should have performed the event you have specified in event_name, input values have to be formatted as integers in format YYYYMMDD

groups – a parent object containing information about properties for which breakdown is required. The endpoint can be used to obtain analysis of multiple properties in one request. Each property object is referenced by a unique key within the groups object

property_type – The type of property for which top breakdown is required. Can be event_properties, session_properties, profile_fields, app_fields, demographics, technographics, reachability or geo_fields. Must be present inside each individual group

name – Name of the property for which top breakdown is required. Must be present along with property_type

The payload structure will be detailed through an example.

Optional Parameters

top_n – The number of top values required for a given property. Can be specified along with property_type and name. Defaults to 10 if absent

orderdesc or asc. Sort order by property value count. Defaults to desc if absent

Refer here for documentation on advanced queries, their structure, and examples.

Valid property_type and name combinations

event_properties – all event properties for the specified event_name

profile_fields – all custom profile fields for the account

session_propertiesutm_source, utm_medium, utm_campaign, session_referrer, session_source, time_of_day (granularity up to hour of day)

app_fields – all app fields

demographics – all demographics fields

technographics – all technographics fields

reachability – all reachability fields

geo_fieldscountry, region, city

Refer here for documentation on properties and their definitions.

Example Payload

{
	"event_name": "Charged",
	"from": 20161229,
	"to": 20170129,
	"groups": {
		"foo": {
			"property_type": "event_properties",
			"name": "Amount"
		},
		"bar": {
			"property_type": "profile_fields",
			"name": "Customer Type",
			"top_n": 2,
			"order": "asc"
		}
	}
}
copy Copied

Response

{
  "status": "success",
  "foo": {
    "NUMBER": {
      "0-100": 10,
      "100-200": 9,
      "200-300": 8,
      "300-400": 7,
      "400-500": 6,
      "500-600": 5,
      "600-700": 4,
      "700-800": 3,
      "800-900": 2,
      "900-1000": 1
    }
  },
  "bar": {
    "STR": {
      "Gold": 5,
      "Silver": 10
    }
  }
}
copy Copied

Each property breakdown is referenced by the unique key assigned to it while querying. Within each property breakdown, there are separate datatype objects denoting the datatype that the property’s values have been provided.

Datatypes can be STR, NUMBER, ENUM, or DATE.

NUMBER and DATE breakdowns are - separated ranges.

DATE values are in UNIX epoch format.

Counts are present within the datatype object for each property breakdown.

Trends API

This endpoint is used to retrieve daily/weekly/monthly event trends in a specified duration (along with optional filters).

Request & Response

With your request, you will specify a JSON formatted query for trends as POST payload along with your CleverTap Account ID and CleverTap Account Passcode in the request headers.

The response to this request will be a JSON object containing status (success/fail).
A successful response containing event trends is detailed later.
If status is fail, the JSON response will contain an error string.

Request Authentication

Every request to the API should include your CleverTap Account ID and CleverTap Account Passcode in the request header keyed with X-CleverTap-Account-Id and X-CleverTap-Passcode, respectively.
Content-Type header must be specified as application/json.

Endpoint

The request to get event counts is an HTTP URL of the following form:

POST https://dashboard.clevertap.com/api/counts/trends

Payload

JSON formatted request with the following parameters

Required Parameters

event_name – The name of the event which has been performed by the users whose events you want to download

from & to – Date range within which users should have performed the event you have specified in event_name, input values have to be formatted as integers in format YYYYMMDD

groups – a parent object containing information about trends whose breakdown is required. The endpoint can be used to obtain analysis of multiple trend in one request. Each trend object is referenced by a unique key within the groups object

trend_type – can be daily, weekly or monthly. Must be present inside each individual group

The payload structure will be detailed through an example.

Optional Parameters

unique – Boolean. If set to true, returns trends of profiles instead of events

Refer here for documentation on advanced queries, their structure, and examples.

Example Payload

{
	"event_name": "UTM Visited",
	"from": 20161224,
	"to": 20170103,
	"unique": false,
	"groups": {
		"foo": {
			"trend_type": "daily"
		},
		"bar": {
			"trend_type": "weekly"
		},
		"foobar": {
			"trend_type": "monthly"
		}
	}
}
copy Copied

Response

{
  "status": "success",
  "foo": {
    "20161224": 10,
    "20161225": 10,
    "20161226": 10,
    "20161227": 10,
    "20161228": 10,
    "20161229": 10,
    "20161230": 10,
    "20161231": 10,
    "20170101": 10,
    "20170102": 10,
    "20170103": 10
  },
  "bar": {
    "201652": 80,
    "201701": 30
  },
  "foobar": {
    "201612": 80,
    "201701": 30
  }
}
copy Copied

Each trend is referenced by the unique key assigned to it while querying.

daily trend keys are in YYYYMMDD format
weekly trend keys are in YYYYWW format, where WW refers to week of year
monthly trend keys are in YYYYMM format

Debugging

HTTP Response Codes

200 Successful request
400 Bad Request. Some mandatory parameter was missing
429 Too many requests were made concurrently.
500 Server Error
Currently, we return 429 when you make more than 3 concurrent requests. Please try again after 10 minutes in case you receive 429 HTTP response code