Documentation > API

Working with Counts API

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

Event Counts API

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

Request & Authentication

Every request to the API should include a JSON formatted query as POST payload, along with your CleverTap Account ID and CleverTap Account Passcode as request headers 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://api.clevertap.com/1/counts/events.json

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

The response would be a JSON object containing the key status, which may be success, partial or fail.

If the status is success, there would be an additional count key with a numeric value of the count for the specified query.

If the status is fail, there would be an additional error key with a a string value, and an appropriate HTTP status code.

If the status is partial, there would be an additional req_id key with a long integer value for the request ID for subsequent querying.

Partial response

{
  "req_id": 384649162721759,
  "status": "partial"
}
copy Copied

Subsequent request using request ID

GET https://api.clevertap.com/1/counts/events.json?req_id=<your_request_id_here>

You would receive a partial response until the query completes executing fully, following which you would receive a success response along with the count if the query was successful, or the fail response with the appropriate error string and HTTP status code.

Success 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 & Authentication

Every request to the API should include a JSON formatted query as POST payload, along with your CleverTap Account ID and CleverTap Account Passcode as request headers 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://api.clevertap.com/1/counts/profiles.json

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

The response would be a JSON object containing the key status, which may be success, partial or fail.

If the status is success, there would be an additional count key with a numeric value of the count for the specified query.

If the status is fail, there would be an additional error key with a a string value, and an appropriate HTTP status code.

If the status is partial, there would be an additional req_id key with a long integer value for the request ID for subsequent querying.

Partial response

{
  "req_id": 384649162721759,
  "status": "partial"
}
copy Copied

Subsequent request using request ID

GET https://api.clevertap.com/1/counts/profiles.json?req_id=<your_request_id_here>

You would receive a partial response until the query completes executing fully, following which you would receive a success response along with the count if the query was successful, or the fail response with the appropriate error string and HTTP status code.

Success 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 & Authentication

With your request you can optionally specify certain parameters within JSON body to retrieve counts (split by specified parameter type).

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://api.clevertap.com/1/now.json

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

The response to this request will be a JSON object containing status (success/fail).
In case of a successful response when no payload was provided:
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

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

Here is a sample response with all optional 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

If the status is fail, there would be an additional error key with a a string value, and an appropriate HTTP status code.

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 & Authentication

Every request to the API should include a JSON formatted query as POST payload, along with your CleverTap Account ID and CleverTap Account Passcode as request headers 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://api.clevertap.com/1/counts/top.json

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

The response would be a JSON object containing the key status, which may be success, partial or fail.

If the status is success, the JSON object would also contain the property breakdown(s) filtered the specified query.

If the status is fail, there would be an additional error key with a a string value, and an appropriate HTTP status code.

If the status is partial, there would be an additional req_id key with a long integer value for the request ID for subsequent querying.

Partial response

{
  "req_id": 384649162721759,
  "status": "partial"
}
copy Copied

Subsequent request using request ID

GET https://api.clevertap.com/1/counts/top.json?req_id=<your_request_id_here>

You would receive a partial response until the query completes executing fully, following which you would receive a success response if the query was successful, or the fail response with the appropriate error string and HTTP status code.

Success 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 & Authentication

Every request to the API should include a JSON formatted query as POST payload, along with your CleverTap Account ID and CleverTap Account Passcode as request headers 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://api.clevertap.com/1/counts/trends.json

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 trends 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

The response would be a JSON object containing the key status, which may be success, partial or fail.

If the status is success, the JSON object would also contain the trend breakdown(s) filtered the specified query.

If the status is fail, there would be an additional error key with a a string value, and an appropriate HTTP status code.

If the status is partial, there would be an additional req_id key with a long integer value for the request ID for subsequent querying.

Partial response

{
  "req_id": 384649162721759,
  "status": "partial"
}
copy Copied

Subsequent request using request ID

GET https://api.clevertap.com/1/counts/trends.json?req_id=<your_request_id_here>

You would receive a partial response until the query completes executing fully, following which you would receive a success response if the query was successful, or the fail response with the appropriate error string and HTTP status code.

Success 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
503 Service Unavailable. Please retry later
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