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.
If you're looking for specific information on the content of those chats, use our Message Report endpoint.
The REST API uses the following path: https://app.certainly.io/api/
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:
Retrieve a Consumption Report (GET)
This method returns a JSON object containing the consumption metrics.
The endpoint path is the following :
This section includes:
Example request cURL (GET)
Headers (GET)
| Header | Description | Example |
| Authorization | Authorization is done via JWT (JSON Web Token) | Authorization: JWT |
| Content_Type | 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 |
| fromDate (string) |
The starting date for the data collection period in your report, formatted as"YYYY-MM-DD". | "2021-12-15" |
| toDate (string) |
The ending date for the data collection period in your report, formatted as"YYYY-MM-DD". | "2021-12-30" |
| includeEmptyResults (bool) |
This optional parameter filters the empty conversations from the results. | false |
| includeTestConversations (bool) |
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)
curl --location --request POST 'https://app.certainly.io/api/frontend/reports/conversations/v2/' \
--header 'Authorization: JWT{{copy_your_user_token_here}}' \
--header 'Content-Type: application/json' \
--data-raw '{
"fromDate":"2021-12-29",
"toDate":"2021-12-30"
}'
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 
Certainly Reports API Webhook Template, which will allow you to easily fetch the information without the need for a third-party API platform.