Billing Usage Summary API

Back to API List

This API provides a summary of the billing usage specific to an account or bot for a given period.

Billing sessions are tracked at the individual app or bot level. In dynamic routing scenarios, the Parent app functions as a standalone app with its own billing sessions. When the Parent app routes a user query to a linked app, that billing session is attributed to the linked app, not the Parent app.

When you select the Parent app in the Admin Console or pass its ID via the API, the system returns only the Parent app’s direct sessions; it doesn’t include sessions routed from the Parent app to linked apps.

Field	Value
Method	POST and GET
Endpoint	POST: For Dialog Builder: https://{{host}}/api/public/bot/{{BotID}}/billingsessionsummary / For BAC: https://{{host}}/api/public/billingsessionsummary Important: First, use the POST method to set filters, then use the following GET method to retrieve the billing session summary. GET: For Dialog Builder: https://{{host}}/api/public/bot/{{BotID}}/billingsessionsummary/status?type=summary / For BAC: https://{{host}}/api/public/billingsessionsummary/status?type=summary
Content Type	application/json
Authorization	auth: {{JWT}} See How to generate the JWT Token.
API Scope	Dialog Builder: Billing Sessions; Admin Console: Billing > Usage > Billing Sessions

Query Parameters

Parameter	Description
host	Environment URL, for example, https://platform.kore.ai.
BotID (when using with Dialog Builder scope)	Bot ID or Stream ID. You can access it from the App Settings page.

Sample Request

Sample POST Method Request for the App Builder API Scope

curl --location 'https://{{HOST}}/api/public/bot/{{botId}}/billingsessionsummary'\
--header 'auth: {{Auth Token}}' \
--header 'content-type: application/json' \
--data-raw '{
"fromDate": "2023-04-07T10:10:54.680Z",
"toDate": "2023-04-09T10:10:54.680Z",
"unitType": ["request","session","alert","proactive","conversations"],
"groupByBot": "no",
"groupByPeriod": "date_day_hour"
}'

Use the POST method to set filters, then use the following GET method to retrieve the billing session summary.

Sample GET Method Request for the App Builder API Scope

curl --location 'https://{{HOST}}/api/public/bot/{{botId}}/billingsessionsummary/status?type=summary'\
--header 'auth: {{Auth Token}}' \
--header 'content-type: application/json'

Sample POST Method Request for the Admin API (BAC) scope

curl --location 'https://{{HOST}}/api/public/bots/billingsessionsummary' \
--header 'auth: {{Auth Token}}' \
--header 'content-type: application/json' \
--data-raw '{
"fromDate": "2022-09-01T07:18:54.089Z",
"toDate": "2022-09-07T23:30:25.931Z",
"unitType": ["session","request","alert","proactive", "conversations"],
"groupByBot": "yes",
"streamIds": ["st-13d7a88d-83cb-52bb-b847-ed32cxxxxxxx"],
"groupByPeriod": "date_month"
}'

Sample GET Method Request for the BAC API Scope

curl --location 'https://{{HOST}}/api/public/bots/billingsessionsummary/status?type=summary'\
--header 'auth: {{Auth Token}}' \
--header 'content-type: application/json'

Body Parameters for the POST Request

Parameter	Required/Optional	Description
fromDate	date, required	Accepts the date in yyyy-mm-dd format or yyyy-mm-ddThh:mm:ss.msZ. Max: 90 days.
toDate	date, required	Accepts the date in yyyy-mm-dd format or yyyy-mm-ddThh:mm:ss.msZ. Max: 90 days.
unitType	string, required	The unit type of the billing session. Possible values: session, request, alert, proactive, conversations.
groupByApp	string, required	Groups billing sessions by Apps. Use yes for BAC scope with stream ID, no for Dialog Builder scope without stream ID.
groupByPeriod	string, required	Retrieve conversation session data on a Monthly, Daily, or Hourly basis. Possible values: date_day_hour, date_day, date_month.

Sample Response

Sample POST Method Response (BAC API Scope)

{
    "reportId": "121242",
    "status": "IN_PROGRESS",
    "percentageComplete": 0,
    "orgId": "o-d54e1923-94e5-5b33-b248-xxxxxxxx",
    "createdBy": "u-093524cf-9df9-5371-b28b-xxxxxxxxx",
    "jobType": "BILLINGSESSIONS_API",
    "action": "QUERY",
    "statusLogs": [],
    "_id": "ds-d7d23763-b876-5219-b93e-6398ea4cb1ec",
    "lMod": "2023-04-27T06:19:11.000Z",
    "createdOn": "2023-04-27T06:19:11.034Z",
    "__v": 0
}

Sample GET Method Responses

Monthly Billing Session Summary

{
"_id": "ds-df7dbe18-9028-59db-8d12-cda96xxxxxx",
"status": "success",
"response": {
  "data": [{
    "bot": "ALL",
    "val": [{
      "date": "2023-04-01T00:00:00.000Z",
      "val": {
        "requests": 0,
        "sessions": 0,
        "alert_notifications": 57,
        "proactive_notifications": 10,
        "conversations": 3
      }
    }]
  }],
  "averageSessions": 70
}
}