Conversation Reporting

Conversation Reporting API

The conversation reporting API enables open-ended queries of your conversation metrics so you can build extensible reporting applications around your team's Drift performance.


Generic body format:

  "filters": [
      "property": string,
      "operation": string (see list of options below),
      "values": [object] (optional, see table below)
  "metrics": [string] //list of property strings
      "property": "lastAgentId",
      "operation": "HAS_PROPERTY"
      "property": "firstCloseAt",
      "operation": "BETWEEN",
      "values": [
        "2019-07-26" //numeric millisecond timestamp may also be used
  "metrics": [

In short, this particular request would request any conversation between two dates that an agent (not just a bot) participated in, and display how long the conversation was open for, how long it took the agent to respond once routed in, the timestamp of the first agent message during the conversation, and the related playbook ID (if applicable) the conversation started from. Note that "agent" is your app user (your sales rep, support agent, etc).


All metrics must be numeric.

    "count": 48,
    "data": [
            "conversationId": 852054511,
            "metrics": [
        }, ...

The response body contains both the number of discovered conversations, as well as the data of the query. The interpretation of this response would be that 48 found conversations between 2019-07-22 and 2019-07-26 contained an agent chatting in, along with data on each conversation (only 1 of the 48 conversations shown above for brevity).


An important note on Reporting API rate limits

The reporting API is subject to stricter rate limits and is subject to a capped rate of 60 calls per minute.

Acceptable Property Values

Use one of the following per metric or filter:


If a metric is not present, will return as "NaN". Metrics must be numeric.

String properties below specified as filter only.

relatedPlaybookIdID of related playbook for the conversation
createdAtTimestamp when the conversation was created (ms)
endUserIdID of the end user (site visitor)
endUserInitiatedTrue/false - whether the end user started the conversation
endUserType (filter only)Type of the end user {USER, END_USER, NONE, LEAD}
firstAgentIdID of the first agent that responded to the conversation
lastAgentIdID of the last agent that responded to the conversation
firstAgentMessageAtTimestamp of the first agent response (ms)
firstBotIdID of the first bot
firstBotMessageAtTimestamp of the first bot message (ms)
firstCloseAtTimestamp of when the conversation was first closed (ms)
firstEndUserMessageAtTimestamp of the first end user message
idID of the conversation
numAgentMessagesNumber of agent messages in the conversation
numBotMessagesNumber of bot messages in the conversation
numEndUserMessagesNumber of end user messages in the conversation
offlineIs the conversation currently offline
pageUrl (filter only)Page url of the conversation
status (filter only)Current status of the conversation, one of {open, closed, pending, archived}
tagsTags on the conversation
timeToAgentResponseMillisTime until the first agent response (ms)
timeToCloseMillisHow long the conversation took to close (ms)
updatedAtLast time the conversation was updated (ms)
botStatusBot status in the conversation, one of { BOT_ONLY, HUMAN_ONLY, BOT_ASSISTED, NO_RESPONSE}
cqlScoreThe current CQL score of the conversation. Values between [-1, 3] corresponding to the number of bolts. -1 means disqualified, 0 means unassigned.

These will be used in the body of the query described below.

Structuring the Query

The query is structured with 2 different properties.


filters - a list of Filter objects. All filters are and'd together.
metrics - a list of properties that represent numeric values for a conversation


property - required the name of an object property.
operation - required a filter operation to be applied to the property
values - a value list to use for comparison (for plural operations such as BETWEEN).

The filters should help narrow down your query to your particular data subset of interest (e.g. all closed conversations between a particular date, or all conversations with an agent (not just bot only) like the sample above).

propertystringProperty (use one of the above property values)
operationstringone of
- EQ - document field exact matches value
- NOT_EQ - document field does not exactly match value
- GT - document field is greater than value
- GTE - document field is greater than or equal to value
- LT - document field is less than value
- LTE - document field is less than or equal to value
- IN - document field is one of values
- NOT_IN - document field is not one of values
- BETWEEN - document field is between the first two items within values
- HAS_PROPERTY - document has the field specified by property
- NOT_HAS_PROPERTY - document does not have the field specified by property
- CONTAINS - document field contains the substring value
- NOT_CONTAINS - document field does not contain the substring value
valuesobject listA value list to use for comparison on plural operations.


property - required the name of an object property to return per conversation

propertystringProperty (use one of the above property values)


A Note on Query Errors

If you get a "check query formatting" error, it can also indicate that your query was accepted syntactically, but was rejected by the search engine. For example, this could occur when a metric property/type pair combination is not supported.


Make your Queries fast

The public conversations reporting API is powerful, but currently not designed for long running queries. In particular, queries will time out after 10 seconds. Please keep them concise.