Query syntax

This document explains how to construct queries for Conversation Insights, including syntax for filtering, grouping, ordering, and pagination.

Query structure

A query request contains the following properties:

1{
2  "domain": "Conversations",
3  "properties": {
4    "timezone": "UTC"
5  },
6  "query": {
7    "measures": [...],
8    "dimensions": [...],
9    "filters": [...],
10    "orderBy": [...]
11  }
12}

Property	Required	Description
`domain`	No	Set to `Conversations`.
`properties`	No	Optional configuration. Supports `timezone`, any valid IANA timezone identifier (for example, `America/Los_Angeles`). Defaults to `UTC`.
`query`	Yes	The query payload containing measures, dimensions, and filters.

Measures

Measures are aggregated values. Specify at least one measure or dimension in your query.

Example: 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();

See Data model for available measures.

Dimensions

Dimensions group your results by categories. When you include dimensions, the API returns one row per unique combination of dimension values.

Example: 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();

1{
2  "items": [
3    { "Conversation.ConversationStatus": "ACTIVE", "Conversation.Count": "15" }
4  ]
5}

Filters

Use filters to narrow your query results. Filters use a nested structure with logical operators (AND, OR) and field expressions.

Example: Query conversation count with multiple filters

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          op: "AND",
21          expressions: [
22            {
23              op: "GT",
24              field: "Conversation.CreatedDate",
25              values: ["2026-04-02"],
26            },
27            {
28              op: "EQ",
29              field: "Conversation.ConversationStatus",
30              values: ["ACTIVE"],
31            },
32          ],
33        },
34      ],
35    },
36  });
37
38  console.log(query.domain);
39}
40
41createQueryResults();

Filter structure

The op property specifies the operator to use. Logical operators (AND, OR) combine multiple expressions at the filter level. Field operators (EQ, NE, GT, LT, IN) compare field values within expressions.

Logical operators

The following logical operators are available:

Operator	Description
`AND`	All expressions must match.
`OR`	At least one expression must match.

Field operators

The following field operators are available:

Operator	Description	Example
`EQ`	Equals	`{ "op": "EQ", "field": "Conversation.ConversationStatus", "values": ["ACTIVE"] }`
`NE`	Not equals	`{ "op": "NE", "field": "Conversation.ConversationStatus", "values": ["CLOSED"] }`
`GT`	Greater than	`{ "op": "GT", "field": "Conversation.CreatedDate", "values": ["2025-01-01"] }`
`LT`	Less than	`{ "op": "LT", "field": "Conversation.CreatedDate", "values": ["2025-02-01"] }`
`IN`	Value is in list	`{ "op": "IN", "field": "Conversation.ConversationStatus", "values": ["ACTIVE"] }`

Combine filters

Combine multiple conditions with logical operators:

1{
2  "filters": [
3    {
4      "op": "AND",
5      "expressions": [
6        { "op": "EQ", "field": "Conversation.ConversationStatus", "values": ["ACTIVE"] },
7        { "op": "GT", "field": "Conversation.CreatedDate", "values": ["2025-01-01"] }
8      ]
9    }
10  ]
11}

Time dimensions

Group results by time periods using time dimensions. Time dimensions use specific dimension names with granularity suffixes.

(information)

Info

All requests must include a greater than (GT) filter on the time dimension.

Example: Query conversation count grouped by day

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.CreatedDate.day"],
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();

Granularity options

Use the following dimension names for different time groupings:

Granularity	Dimension name	Description
`hour`	`Conversation.CreatedDate.hour`	Group by hour.
`day`	`Conversation.CreatedDate.day`	Group by day.
`week`	`Conversation.CreatedDate.week`	Group by week.
`month`	`Conversation.CreatedDate.month`	Group by month.

Timezone

Use the properties.timezone field to control how time-based dimensions and groupings are evaluated. If not specified, the API defaults to UTC.

The timezone field accepts any valid Internet Assigned Numbers Authority (IANA) timezone identifier (for example, UTC, America/Los_Angeles, Europe/Berlin).

Example: Query conversation count grouped by day in a specific timezone

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.CreatedDate.day"],
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();

Order results

Sort results by a field in ascending or descending order:

Example: Query conversation count by status, ordered by count descending

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      orderBy: [
31        {
32          field: "Conversation.Count",
33          direction: "DESC",
34        },
35      ],
36    },
37  });
38
39  console.log(query.domain);
40}
41
42createQueryResults();

The orderBy property accepts the following fields:

Property	Description
`field`	The measure or dimension to sort by.
`direction`	Sort direction: `ASC` (ascending) or `DESC` (descending).

Pagination

Use the pageSize and pageToken query parameters to paginate through results.

To set the page size, add the pageSize query parameter to your POST request. The default is 50 and the maximum is 1000.

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

The response includes a nextToken in the meta object. To fetch the next page, send a GET request with the pageToken query parameter:

1curl -X GET "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query?pageToken=NEXT_PAGE_TOKEN" \
2  -u $TWILIO_API_KEY:$TWILIO_API_SECRET \
3  -H "Content-Type: application/json"

Next steps

Explore the following resources to learn more:

Aggregate conversation data
Data model: see all available measures and dimensions.