Consumption Report endpoint

The Consumption Report endpoint allows you to retrieve metrics about your bot(s) over a certain period of time. The metrics contain information such as the name of the bot, which channel it's deployed to, the number of conversations it has had, the number of messages that have been exchanged, and more.

It does not provide specific information regarding the content of those chats. For that, you can use our Message Report endpoint.

The Consumption Report endpoint can be called through the use of HTTP GET and POST, depending on the response format you require. Below, we'll explore both methods:

The REST API uses the following path: 

Retrieve a Consumption Report (GET)

This method returns a JSON object containing the consumption metrics.

The endpoint path is the following :


{  "author_id": 35436,  "created_at": "2009-07-20T22:55:29Z",  "events": [    {      "attachments": [],      "body": "Thanks for your help!",      "id": 1564245,      "public": true,      "type": "Comment"    },    {      "body": "Ticket #47 has been updated",      "id": 1564246,      "subject": "Your ticket has been updated",      "type": "Notification"    }  ],  "id": 35436,  "metadata": {    "custom": {      "time_spent": "3m22s"    },    "system": {      "ip_address": ""    }  },  "ticket_id": 47,  "via": {    "channel": "web"  }}


This section includes:

Example request cURL (GET)



Headers (GET)

Header Description Example


Authorization is done via JWT (JSON Web Token)*

Authorization: JWT {{copy_your_user_token_here}}


The endpoint response is in JSON format. For this reason, it is necessary to indicate that the Content-Type is application/json. Content-Type: application/json

*You can fetch your user token by heading to the Navigation bar and clicking on "user name" when it drops down from the "My Profile" icon at the top right. There, you'll see a field named "public API auth token".

Query parameters (GET)

Query Description Example


The starting date for the data collection period in your report, formatted as"YYYY-MM-DD". "2021-12-15"


The ending date for the data collection period in your report, formatted as"YYYY-MM-DD". "2021-12-30"


This optional parameter filters the empty conversations from the results. false


This optional parameter filters those conversations performed in the bot's testing environment. false

Example response (GET)



Get a Consumption Report via email (POST)

This request is asynchronous, and it triggers the sending of a dataset to the email account linked to the authentication token used. The report is attached to the email as an Excel file. 

The endpoint that is attached under the domain is as follows:



This section includes:

Example request cURL (POST)


Headers (POST)

The headers for this request are the same as those used for the GET request above.

Body (POST)

Since this is a POST request, the request must be accompanied by a request body that contains a JSON document with the following parameters:


You will find a more in-depth explanation of the different parameters above.

Example response (POST)

A successful request returns the following response:



To simplify the process of making this request, we've created the <wh>Codemonkey Reports API Webhook Template, which will allow you to easily fetch the information without the need for a third-party API platform.

Was this article helpful?

0 out of 0 found this helpful
Have more questions? Submit a request

Comments (0 comments)

Please sign in to leave a comment.