Aggregate conversation data with Conversation Insights

Use Conversation Insights to discover available data and aggregate your conversation metrics. This guide walks through querying the Metadata and Query endpoints to count conversations, add dimensions, and filter results.

Prerequisites

Complete the prerequisites:

Create a Twilio account.
Store your Twilio credentials in environment variables.
Set up Conversation Orchestrator with at least one conversation.

(information)

Info

Insights data becomes available approximately 15 minutes after conversation events.

Discover available data

Before querying, use the Metadata API to see what measures and dimensions are available.

Send a GET request to the Metadata endpoint:

Retrieve available measures and dimensions

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function fetchMetadata() {
14  const metadata = await client.insights.v3.metadata.fetch();
15
16  console.log(metadata.domain);
17}
18
19fetchMetadata();

The response includes a list of cubes, each with its available measures and dimensions.

1{
2  "domain": "Conversations",
3  "cubes": [
4    {
5      "name": "Conversation",
6      "description": "Contains aggregated conversation event data",
7      "measures": [
8        {
9          "name": "Conversation.Count",
10          "type": "number",
11          "aggregation": "countDistinct",
12          "description": "The count of unique conversations"
13        }
14      ],
15      "dimensions": [
16        {
17          "name": "Conversation.ConversationId",
18          "type": "string",
19          "description": "The unique identifier for the conversation"
20        }
21      ]
22    }
23  ]
24}

Aggregate total conversation count

To get the total conversation count, make a POST request to the Query endpoint.

Query total conversation count

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createQueryResults() {
14  const query = await client.insights.v3.query.create({
15    domain: "Conversations",
16    query: {
17      measures: ["Conversation.Count"],
18      filters: [
19        {
20          expressions: [
21            {
22              op: "GT",
23              field: "Conversation.CreatedDate",
24              values: ["2026-04-02"],
25            },
26          ],
27        },
28      ],
29    },
30  });
31
32  console.log(query.domain);
33}
34
35createQueryResults();

The response includes your aggregated data:

1{
2  "domain": "Conversations",
3  "items": [
4    {
5      "Conversation.Count": "2"
6    }
7  ],
8  "meta": {
9    "key": "items",
10    "nextToken": null,
11    "pageSize": 50,
12    "previousToken": null
13  }
14}

Add dimensions

Query conversations grouped by dimensions. This example counts conversations by status:

Query conversation count by status

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createQueryResults() {
14  const query = await client.insights.v3.query.create({
15    domain: "Conversations",
16    query: {
17      measures: ["Conversation.Count"],
18      dimensions: ["Conversation.ConversationStatus"],
19      filters: [
20        {
21          expressions: [
22            {
23              op: "GT",
24              field: "Conversation.CreatedDate",
25              values: ["2026-04-02"],
26            },
27          ],
28        },
29      ],
30    },
31  });
32
33  console.log(query.domain);
34}
35
36createQueryResults();

The response groups results by status:

1{
2  "domain": "Conversations",
3  "items": [
4    {
5      "Conversation.ConversationStatus": "ACTIVE",
6      "Conversation.Count": "15"
7    }
8  ],
9  "meta": {
10    "key": "items",
11    "nextToken": null,
12    "pageSize": 50,
13    "previousToken": null
14  }
15}

Count operator results

Query operator results to analyze intelligence operators run on your conversations. This example counts operator results grouped by operator name:

Query operator result count by operator name

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createQueryResults() {
14  const query = await client.insights.v3.query.create({
15    domain: "Conversations",
16    query: {
17      measures: ["OperatorResult.Count"],
18      dimensions: ["OperatorResult.OperatorName"],
19      filters: [
20        {
21          expressions: [
22            {
23              op: "GT",
24              field: "OperatorResult.CreatedDate",
25              values: ["2026-04-02"],
26            },
27          ],
28        },
29      ],
30    },
31  });
32
33  console.log(query.domain);
34}
35
36createQueryResults();

The response groups results by operator name:

1{
2  "domain": "Conversations",
3  "items": [
4    {
5      "OperatorResult.Count": "168",
6      "OperatorResult.OperatorName": "Sentiment"
7    }
8  ],
9  "meta": {
10    "key": "items",
11    "nextToken": null,
12    "pageSize": 1,
13    "previousToken": null
14  }
15}

Filter by Knowledge Base

Query operator results that used a specific Knowledge Base. This example retrieves conversations and operator names filtered by Knowledge Base ID:

Query operator results filtered by Knowledge Base ID

1// Download the helper library from https://www.twilio.com/docs/node/install
2const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";
3
4// Find your Account SID at twilio.com/console
5// Provision API Keys at twilio.com/console/runtime/api-keys
6// and set the environment variables. See http://twil.io/secure
7// For local testing, you can use your Account SID and Auth token
8const accountSid = process.env.TWILIO_ACCOUNT_SID;
9const apiKey = process.env.TWILIO_API_KEY;
10const apiSecret = process.env.TWILIO_API_SECRET;
11const client = twilio(apiKey, apiSecret, { accountSid: accountSid });
12
13async function createQueryResults() {
14  const query = await client.insights.v3.query.create({
15    domain: "Conversations",
16    query: {
17      dimensions: [
18        "OperatorResult.ConversationId",
19        "OperatorResult.OperatorName",
20        "OperatorResult.KnowledgeBaseId",
21      ],
22      filters: [
23        {
24          op: "AND",
25          expressions: [
26            {
27              op: "GT",
28              field: "OperatorResult.CreatedDate",
29              values: ["2026-04-10"],
30            },
31            {
32              op: "EQ",
33              field: "OperatorResult.KnowledgeBaseId",
34              values: ["know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"],
35            },
36          ],
37        },
38      ],
39    },
40  });
41
42  console.log(query.domain);
43}
44
45createQueryResults();

The response returns operator results filtered by the specified Knowledge Base:

1{
2  "domain": "Conversations",
3  "items": [
4    {
5      "OperatorResult.ConversationId": "conv_conversation_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
6      "OperatorResult.OperatorName": "Sentiment",
7      "OperatorResult.KnowledgeBaseId": "know_knowledgebase_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"
8    }
9  ],
10  "meta": {
11    "key": "items",
12    "nextToken": null,
13    "pageSize": 1,
14    "previousToken": null
15  }
16}

Run queries asynchronously

To run queries asynchronously, use the QueryJobs resource instead of the Query resource. If you don't need results immediately, such as a query that takes longer than a synchronous request allows, you can submit it and check back for results later.

1curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs" \
2  -u $TWILIO_API_KEY:$TWILIO_API_SECRET \
3  -H "Content-Type: application/json" \
4  -d '{
5    "domain": "Conversations",
6    "query": {
7      "dimensions": ["OperatorResult.ConversationId", "OperatorResult.OperatorName", "OperatorResult.OperatorLabel"],
8      "filters": [
9        {
10          "expressions": [
11            {
12              "op": "GT",
13              "field": "OperatorResult.CreatedDate",
14              "values": ["2026-01-01"]
15            }
16          ]
17        }
18      ]
19    }
20  }'

Twilio returns an operationId and a statusUrl. See Asynchronous queries for how to poll for completion and retrieve results.

Next steps

To learn more about Conversation Insights, see the following resources:

Data model: Understand cubes, measures, and dimensions.
Query syntax: Learn how to construct complex queries with filters, ordering, and pagination.