# 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:

```json
{
  "domain": "Conversations",
  "properties": {
    "timezone": "UTC"
  },
  "query": {
    "measures": [...],
    "dimensions": [...],
    "filters": [...],
    "orderBy": [...]
  }
}
```

| 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

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createQueryResults() {
  const query = await client.insights.v3.query.create({
    domain: "Conversations",
    query: {
      measures: ["Conversation.Count"],
      filters: [
        {
          expressions: [
            {
              op: "GT",
              field: "Conversation.CreatedDate",
              values: ["2026-04-02"],
            },
          ],
        },
      ],
    },
  });

  console.log(query.domain);
}

createQueryResults();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.insights.v3 import QueryList

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

query = client.insights.v3.query.create(
    insights_query_request=QueryList.InsightsQueryRequest(
        {
            "domain": "Conversations",
            "query": QueryList.QueryDefinition(
                {
                    "measures": ["Conversation.Count"],
                    "filters": [
                        QueryList.QueryDefinitionFilters(
                            {
                                "expressions": [
                                    QueryList.QueryDefinitionFiltersExpressions(
                                        {
                                            "op": "GT",
                                            "field": "Conversation.CreatedDate",
                                            "values": ["2026-04-02"],
                                        }
                                    )
                                ]
                            }
                        )
                    ],
                }
            ),
        }
    )
)

print(query.domain)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Insights.V3;
using System.Threading.Tasks;
using System.Collections.Generic;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var query = await QueryResource.CreateAsync(
            insightsQueryRequest: new QueryResource.InsightsQueryRequest.Builder()
                .WithDomain("Conversations")
                .WithQuery(
                    new QueryResource.QueryDefinition.Builder()
                        .WithMeasures(new List<string> { "Conversation.Count" })
                        .WithFilters(new List<QueryResource.QueryDefinitionFilters> {
                            new QueryResource.QueryDefinitionFilters.Builder()
                                .WithExpressions(
                                    new List<QueryResource.QueryDefinitionFiltersExpressions> {
                                        new QueryResource.QueryDefinitionFiltersExpressions
                                            .Builder()
                                            .WithOp("GT")
                                            .WithField("Conversation.CreatedDate")
                                            .WithValues(new List<string> { "2026-04-02" })
                                            .Build()
                                    })
                                .Build()
                        })
                        .Build())
                .Build());

        Console.WriteLine(query.Domain);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.twilio.Twilio;
import com.twilio.rest.insights.v3.Query;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);

        Query.QueryDefinitionFiltersExpressions queryDefinitionFiltersExpressions1 =
            Query.QueryDefinitionFiltersExpressions.builder(Query.Op.GT, "Conversation.CreatedDate")
                .values(Arrays.asList("2026-04-02"))
                .build();

        Query.QueryDefinitionFilters queryDefinitionFilters1 =
            Query.QueryDefinitionFilters.builder(Arrays.asList(queryDefinitionFiltersExpressions1)).build();

        Query.QueryDefinition queryDefinition = Query.QueryDefinition.builder()
                                                    .measures(Arrays.asList("Conversation.Count"))
                                                    .filters(Arrays.asList(queryDefinitionFilters1))
                                                    .build();

        Query.InsightsQueryRequest insightsQueryRequest =
            Query.InsightsQueryRequest.builder(queryDefinition).domain("Conversations").build();

        Query.CreateQueryResponse response = Query.creator(insightsQueryRequest).create();

        System.out.println(response.getDomain());
    }
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

query = @client
        .insights
        .v3
        .query
        .create(
          insights_query_request: {
            'domain' => 'Conversations',
            'query' => {
              'measures' => [
                'Conversation.Count'
              ],
              'filters' => [
                {
                  'expressions' => [
                    {
                      'op' => 'GT',
                      'field' => 'Conversation.CreatedDate',
                      'values' => [
                        '2026-04-02'
                      ]
                    }
                  ]
                }
              ]
            }
          }
        )

puts query.domain
```

```bash
INSIGHTS_QUERY_REQUEST_OBJ=$(cat << EOF
{
  "domain": "Conversations",
  "query": {
    "measures": [
      "Conversation.Count"
    ],
    "filters": [
      {
        "expressions": [
          {
            "op": "GT",
            "field": "Conversation.CreatedDate",
            "values": [
              "2026-04-02"
            ]
          }
        ]
      }
    ]
  }
}
EOF
)
curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query" \
--json "$INSIGHTS_QUERY_REQUEST_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

See [Data model](/docs/conversations/intelligence/conversation-insights/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

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createQueryResults() {
  const query = await client.insights.v3.query.create({
    domain: "Conversations",
    query: {
      measures: ["Conversation.Count"],
      dimensions: ["Conversation.ConversationStatus"],
      filters: [
        {
          expressions: [
            {
              op: "GT",
              field: "Conversation.CreatedDate",
              values: ["2026-04-02"],
            },
          ],
        },
      ],
    },
  });

  console.log(query.domain);
}

createQueryResults();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.insights.v3 import QueryList

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

query = client.insights.v3.query.create(
    insights_query_request=QueryList.InsightsQueryRequest(
        {
            "domain": "Conversations",
            "query": QueryList.QueryDefinition(
                {
                    "measures": ["Conversation.Count"],
                    "dimensions": ["Conversation.ConversationStatus"],
                    "filters": [
                        QueryList.QueryDefinitionFilters(
                            {
                                "expressions": [
                                    QueryList.QueryDefinitionFiltersExpressions(
                                        {
                                            "op": "GT",
                                            "field": "Conversation.CreatedDate",
                                            "values": ["2026-04-02"],
                                        }
                                    )
                                ]
                            }
                        )
                    ],
                }
            ),
        }
    )
)

print(query.domain)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Insights.V3;
using System.Threading.Tasks;
using System.Collections.Generic;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var query = await QueryResource.CreateAsync(
            insightsQueryRequest: new QueryResource.InsightsQueryRequest.Builder()
                .WithDomain("Conversations")
                .WithQuery(
                    new QueryResource.QueryDefinition.Builder()
                        .WithMeasures(new List<string> { "Conversation.Count" })
                        .WithDimensions(new List<string> { "Conversation.ConversationStatus" })
                        .WithFilters(new List<QueryResource.QueryDefinitionFilters> {
                            new QueryResource.QueryDefinitionFilters.Builder()
                                .WithExpressions(
                                    new List<QueryResource.QueryDefinitionFiltersExpressions> {
                                        new QueryResource.QueryDefinitionFiltersExpressions
                                            .Builder()
                                            .WithOp("GT")
                                            .WithField("Conversation.CreatedDate")
                                            .WithValues(new List<string> { "2026-04-02" })
                                            .Build()
                                    })
                                .Build()
                        })
                        .Build())
                .Build());

        Console.WriteLine(query.Domain);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.twilio.Twilio;
import com.twilio.rest.insights.v3.Query;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);

        Query.QueryDefinitionFiltersExpressions queryDefinitionFiltersExpressions1 =
            Query.QueryDefinitionFiltersExpressions.builder(Query.Op.GT, "Conversation.CreatedDate")
                .values(Arrays.asList("2026-04-02"))
                .build();

        Query.QueryDefinitionFilters queryDefinitionFilters1 =
            Query.QueryDefinitionFilters.builder(Arrays.asList(queryDefinitionFiltersExpressions1)).build();

        Query.QueryDefinition queryDefinition = Query.QueryDefinition.builder()
                                                    .measures(Arrays.asList("Conversation.Count"))
                                                    .dimensions(Arrays.asList("Conversation.ConversationStatus"))
                                                    .filters(Arrays.asList(queryDefinitionFilters1))
                                                    .build();

        Query.InsightsQueryRequest insightsQueryRequest =
            Query.InsightsQueryRequest.builder(queryDefinition).domain("Conversations").build();

        Query.CreateQueryResponse response = Query.creator(insightsQueryRequest).create();

        System.out.println(response.getDomain());
    }
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

query = @client
        .insights
        .v3
        .query
        .create(
          insights_query_request: {
            'domain' => 'Conversations',
            'query' => {
              'measures' => [
                'Conversation.Count'
              ],
              'dimensions' => [
                'Conversation.ConversationStatus'
              ],
              'filters' => [
                {
                  'expressions' => [
                    {
                      'op' => 'GT',
                      'field' => 'Conversation.CreatedDate',
                      'values' => [
                        '2026-04-02'
                      ]
                    }
                  ]
                }
              ]
            }
          }
        )

puts query.domain
```

```bash
INSIGHTS_QUERY_REQUEST_OBJ=$(cat << EOF
{
  "domain": "Conversations",
  "query": {
    "measures": [
      "Conversation.Count"
    ],
    "dimensions": [
      "Conversation.ConversationStatus"
    ],
    "filters": [
      {
        "expressions": [
          {
            "op": "GT",
            "field": "Conversation.CreatedDate",
            "values": [
              "2026-04-02"
            ]
          }
        ]
      }
    ]
  }
}
EOF
)
curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query" \
--json "$INSIGHTS_QUERY_REQUEST_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

```json
{
  "items": [
    { "Conversation.ConversationStatus": "ACTIVE", "Conversation.Count": "15" }
  ]
}
```

## 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

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createQueryResults() {
  const query = await client.insights.v3.query.create({
    domain: "Conversations",
    query: {
      measures: ["Conversation.Count"],
      filters: [
        {
          op: "AND",
          expressions: [
            {
              op: "GT",
              field: "Conversation.CreatedDate",
              values: ["2026-04-02"],
            },
            {
              op: "EQ",
              field: "Conversation.ConversationStatus",
              values: ["ACTIVE"],
            },
          ],
        },
      ],
    },
  });

  console.log(query.domain);
}

createQueryResults();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.insights.v3 import QueryList

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

query = client.insights.v3.query.create(
    insights_query_request=QueryList.InsightsQueryRequest(
        {
            "domain": "Conversations",
            "query": QueryList.QueryDefinition(
                {
                    "measures": ["Conversation.Count"],
                    "filters": [
                        QueryList.QueryDefinitionFilters(
                            {
                                "op": "AND",
                                "expressions": [
                                    QueryList.QueryDefinitionFiltersExpressions(
                                        {
                                            "op": "GT",
                                            "field": "Conversation.CreatedDate",
                                            "values": ["2026-04-02"],
                                        }
                                    ),
                                    QueryList.QueryDefinitionFiltersExpressions(
                                        {
                                            "op": "EQ",
                                            "field": "Conversation.ConversationStatus",
                                            "values": ["ACTIVE"],
                                        }
                                    ),
                                ],
                            }
                        )
                    ],
                }
            ),
        }
    )
)

print(query.domain)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Insights.V3;
using System.Threading.Tasks;
using System.Collections.Generic;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var query = await QueryResource.CreateAsync(
            insightsQueryRequest: new QueryResource.InsightsQueryRequest.Builder()
                .WithDomain("Conversations")
                .WithQuery(
                    new QueryResource.QueryDefinition.Builder()
                        .WithMeasures(new List<string> { "Conversation.Count" })
                        .WithFilters(new List<QueryResource.QueryDefinitionFilters> {
                            new QueryResource.QueryDefinitionFilters.Builder()
                                .WithOp("AND")
                                .WithExpressions(new List<
                                                 QueryResource.QueryDefinitionFiltersExpressions> {
                                    new QueryResource.QueryDefinitionFiltersExpressions.Builder()
                                        .WithOp("GT")
                                        .WithField("Conversation.CreatedDate")
                                        .WithValues(new List<string> { "2026-04-02" })
                                        .Build(),
                                    new QueryResource.QueryDefinitionFiltersExpressions.Builder()
                                        .WithOp("EQ")
                                        .WithField("Conversation.ConversationStatus")
                                        .WithValues(new List<string> { "ACTIVE" })
                                        .Build()
                                })
                                .Build()
                        })
                        .Build())
                .Build());

        Console.WriteLine(query.Domain);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.twilio.Twilio;
import com.twilio.rest.insights.v3.Query;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);

        Query.QueryDefinitionFiltersExpressions queryDefinitionFiltersExpressions1 =
            Query.QueryDefinitionFiltersExpressions.builder(Query.Op.GT, "Conversation.CreatedDate")
                .values(Arrays.asList("2026-04-02"))
                .build();

        Query.QueryDefinitionFiltersExpressions queryDefinitionFiltersExpressions2 =
            Query.QueryDefinitionFiltersExpressions.builder(Query.Op.EQ, "Conversation.ConversationStatus")
                .values(Arrays.asList("ACTIVE"))
                .build();

        Query.QueryDefinitionFilters queryDefinitionFilters1 =
            Query.QueryDefinitionFilters
                .builder(Arrays.asList(queryDefinitionFiltersExpressions1, queryDefinitionFiltersExpressions2))
                .op(Query.Op.AND)
                .build();

        Query.QueryDefinition queryDefinition = Query.QueryDefinition.builder()
                                                    .measures(Arrays.asList("Conversation.Count"))
                                                    .filters(Arrays.asList(queryDefinitionFilters1))
                                                    .build();

        Query.InsightsQueryRequest insightsQueryRequest =
            Query.InsightsQueryRequest.builder(queryDefinition).domain("Conversations").build();

        Query.CreateQueryResponse response = Query.creator(insightsQueryRequest).create();

        System.out.println(response.getDomain());
    }
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

query = @client
        .insights
        .v3
        .query
        .create(
          insights_query_request: {
            'domain' => 'Conversations',
            'query' => {
              'measures' => [
                'Conversation.Count'
              ],
              'filters' => [
                {
                  'op' => 'AND',
                  'expressions' => [
                    {
                      'op' => 'GT',
                      'field' => 'Conversation.CreatedDate',
                      'values' => [
                        '2026-04-02'
                      ]
                    },
                    {
                      'op' => 'EQ',
                      'field' => 'Conversation.ConversationStatus',
                      'values' => [
                        'ACTIVE'
                      ]
                    }
                  ]
                }
              ]
            }
          }
        )

puts query.domain
```

```bash
INSIGHTS_QUERY_REQUEST_OBJ=$(cat << EOF
{
  "domain": "Conversations",
  "query": {
    "measures": [
      "Conversation.Count"
    ],
    "filters": [
      {
        "op": "AND",
        "expressions": [
          {
            "op": "GT",
            "field": "Conversation.CreatedDate",
            "values": [
              "2026-04-02"
            ]
          },
          {
            "op": "EQ",
            "field": "Conversation.ConversationStatus",
            "values": [
              "ACTIVE"
            ]
          }
        ]
      }
    ]
  }
}
EOF
)
curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query" \
--json "$INSIGHTS_QUERY_REQUEST_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

### 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:

```json
{
  "filters": [
    {
      "op": "AND",
      "expressions": [
        { "op": "EQ", "field": "Conversation.ConversationStatus", "values": ["ACTIVE"] },
        { "op": "GT", "field": "Conversation.CreatedDate", "values": ["2025-01-01"] }
      ]
    }
  ]
}
```

## Time dimensions

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

> \[!NOTE]
>
> All requests must include a greater than (`GT`) filter on the time dimension.

Example: Query conversation count grouped by day

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createQueryResults() {
  const query = await client.insights.v3.query.create({
    domain: "Conversations",
    query: {
      measures: ["Conversation.Count"],
      dimensions: ["Conversation.CreatedDate.day"],
      filters: [
        {
          expressions: [
            {
              op: "GT",
              field: "Conversation.CreatedDate",
              values: ["2026-04-02"],
            },
          ],
        },
      ],
    },
  });

  console.log(query.domain);
}

createQueryResults();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.insights.v3 import QueryList

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

query = client.insights.v3.query.create(
    insights_query_request=QueryList.InsightsQueryRequest(
        {
            "domain": "Conversations",
            "query": QueryList.QueryDefinition(
                {
                    "measures": ["Conversation.Count"],
                    "dimensions": ["Conversation.CreatedDate.day"],
                    "filters": [
                        QueryList.QueryDefinitionFilters(
                            {
                                "expressions": [
                                    QueryList.QueryDefinitionFiltersExpressions(
                                        {
                                            "op": "GT",
                                            "field": "Conversation.CreatedDate",
                                            "values": ["2026-04-02"],
                                        }
                                    )
                                ]
                            }
                        )
                    ],
                }
            ),
        }
    )
)

print(query.domain)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Insights.V3;
using System.Threading.Tasks;
using System.Collections.Generic;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var query = await QueryResource.CreateAsync(
            insightsQueryRequest: new QueryResource.InsightsQueryRequest.Builder()
                .WithDomain("Conversations")
                .WithQuery(
                    new QueryResource.QueryDefinition.Builder()
                        .WithMeasures(new List<string> { "Conversation.Count" })
                        .WithDimensions(new List<string> { "Conversation.CreatedDate.day" })
                        .WithFilters(new List<QueryResource.QueryDefinitionFilters> {
                            new QueryResource.QueryDefinitionFilters.Builder()
                                .WithExpressions(
                                    new List<QueryResource.QueryDefinitionFiltersExpressions> {
                                        new QueryResource.QueryDefinitionFiltersExpressions
                                            .Builder()
                                            .WithOp("GT")
                                            .WithField("Conversation.CreatedDate")
                                            .WithValues(new List<string> { "2026-04-02" })
                                            .Build()
                                    })
                                .Build()
                        })
                        .Build())
                .Build());

        Console.WriteLine(query.Domain);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.twilio.Twilio;
import com.twilio.rest.insights.v3.Query;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);

        Query.QueryDefinitionFiltersExpressions queryDefinitionFiltersExpressions1 =
            Query.QueryDefinitionFiltersExpressions.builder(Query.Op.GT, "Conversation.CreatedDate")
                .values(Arrays.asList("2026-04-02"))
                .build();

        Query.QueryDefinitionFilters queryDefinitionFilters1 =
            Query.QueryDefinitionFilters.builder(Arrays.asList(queryDefinitionFiltersExpressions1)).build();

        Query.QueryDefinition queryDefinition = Query.QueryDefinition.builder()
                                                    .measures(Arrays.asList("Conversation.Count"))
                                                    .dimensions(Arrays.asList("Conversation.CreatedDate.day"))
                                                    .filters(Arrays.asList(queryDefinitionFilters1))
                                                    .build();

        Query.InsightsQueryRequest insightsQueryRequest =
            Query.InsightsQueryRequest.builder(queryDefinition).domain("Conversations").build();

        Query.CreateQueryResponse response = Query.creator(insightsQueryRequest).create();

        System.out.println(response.getDomain());
    }
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

query = @client
        .insights
        .v3
        .query
        .create(
          insights_query_request: {
            'domain' => 'Conversations',
            'query' => {
              'measures' => [
                'Conversation.Count'
              ],
              'dimensions' => [
                'Conversation.CreatedDate.day'
              ],
              'filters' => [
                {
                  'expressions' => [
                    {
                      'op' => 'GT',
                      'field' => 'Conversation.CreatedDate',
                      'values' => [
                        '2026-04-02'
                      ]
                    }
                  ]
                }
              ]
            }
          }
        )

puts query.domain
```

```bash
INSIGHTS_QUERY_REQUEST_OBJ=$(cat << EOF
{
  "domain": "Conversations",
  "query": {
    "measures": [
      "Conversation.Count"
    ],
    "dimensions": [
      "Conversation.CreatedDate.day"
    ],
    "filters": [
      {
        "expressions": [
          {
            "op": "GT",
            "field": "Conversation.CreatedDate",
            "values": [
              "2026-04-02"
            ]
          }
        ]
      }
    ]
  }
}
EOF
)
curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query" \
--json "$INSIGHTS_QUERY_REQUEST_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

### 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

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createQueryResults() {
  const query = await client.insights.v3.query.create({
    domain: "Conversations",
    query: {
      measures: ["Conversation.Count"],
      dimensions: ["Conversation.CreatedDate.day"],
      filters: [
        {
          expressions: [
            {
              op: "GT",
              field: "Conversation.CreatedDate",
              values: ["2026-04-02"],
            },
          ],
        },
      ],
    },
  });

  console.log(query.domain);
}

createQueryResults();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.insights.v3 import QueryList

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

query = client.insights.v3.query.create(
    insights_query_request=QueryList.InsightsQueryRequest(
        {
            "domain": "Conversations",
            "query": QueryList.QueryDefinition(
                {
                    "measures": ["Conversation.Count"],
                    "dimensions": ["Conversation.CreatedDate.day"],
                    "filters": [
                        QueryList.QueryDefinitionFilters(
                            {
                                "expressions": [
                                    QueryList.QueryDefinitionFiltersExpressions(
                                        {
                                            "op": "GT",
                                            "field": "Conversation.CreatedDate",
                                            "values": ["2026-04-02"],
                                        }
                                    )
                                ]
                            }
                        )
                    ],
                }
            ),
        }
    )
)

print(query.domain)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Insights.V3;
using System.Threading.Tasks;
using System.Collections.Generic;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var query = await QueryResource.CreateAsync(
            insightsQueryRequest: new QueryResource.InsightsQueryRequest.Builder()
                .WithDomain("Conversations")
                .WithQuery(
                    new QueryResource.QueryDefinition.Builder()
                        .WithMeasures(new List<string> { "Conversation.Count" })
                        .WithDimensions(new List<string> { "Conversation.CreatedDate.day" })
                        .WithFilters(new List<QueryResource.QueryDefinitionFilters> {
                            new QueryResource.QueryDefinitionFilters.Builder()
                                .WithExpressions(
                                    new List<QueryResource.QueryDefinitionFiltersExpressions> {
                                        new QueryResource.QueryDefinitionFiltersExpressions
                                            .Builder()
                                            .WithOp("GT")
                                            .WithField("Conversation.CreatedDate")
                                            .WithValues(new List<string> { "2026-04-02" })
                                            .Build()
                                    })
                                .Build()
                        })
                        .Build())
                .Build());

        Console.WriteLine(query.Domain);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.twilio.Twilio;
import com.twilio.rest.insights.v3.Query;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);

        Query.QueryDefinitionFiltersExpressions queryDefinitionFiltersExpressions1 =
            Query.QueryDefinitionFiltersExpressions.builder(Query.Op.GT, "Conversation.CreatedDate")
                .values(Arrays.asList("2026-04-02"))
                .build();

        Query.QueryDefinitionFilters queryDefinitionFilters1 =
            Query.QueryDefinitionFilters.builder(Arrays.asList(queryDefinitionFiltersExpressions1)).build();

        Query.QueryDefinition queryDefinition = Query.QueryDefinition.builder()
                                                    .measures(Arrays.asList("Conversation.Count"))
                                                    .dimensions(Arrays.asList("Conversation.CreatedDate.day"))
                                                    .filters(Arrays.asList(queryDefinitionFilters1))
                                                    .build();

        Query.InsightsQueryRequest insightsQueryRequest =
            Query.InsightsQueryRequest.builder(queryDefinition).domain("Conversations").build();

        Query.CreateQueryResponse response = Query.creator(insightsQueryRequest).create();

        System.out.println(response.getDomain());
    }
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

query = @client
        .insights
        .v3
        .query
        .create(
          insights_query_request: {
            'domain' => 'Conversations',
            'query' => {
              'measures' => [
                'Conversation.Count'
              ],
              'dimensions' => [
                'Conversation.CreatedDate.day'
              ],
              'filters' => [
                {
                  'expressions' => [
                    {
                      'op' => 'GT',
                      'field' => 'Conversation.CreatedDate',
                      'values' => [
                        '2026-04-02'
                      ]
                    }
                  ]
                }
              ]
            }
          }
        )

puts query.domain
```

```bash
INSIGHTS_QUERY_REQUEST_OBJ=$(cat << EOF
{
  "domain": "Conversations",
  "query": {
    "measures": [
      "Conversation.Count"
    ],
    "dimensions": [
      "Conversation.CreatedDate.day"
    ],
    "filters": [
      {
        "expressions": [
          {
            "op": "GT",
            "field": "Conversation.CreatedDate",
            "values": [
              "2026-04-02"
            ]
          }
        ]
      }
    ]
  }
}
EOF
)
curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query" \
--json "$INSIGHTS_QUERY_REQUEST_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

## Order results

Sort results by a field in ascending or descending order:

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

```js
// Download the helper library from https://www.twilio.com/docs/node/install
const twilio = require("twilio"); // Or, for ESM: import twilio from "twilio";

// Find your Account SID at twilio.com/console
// Provision API Keys at twilio.com/console/runtime/api-keys
// and set the environment variables. See http://twil.io/secure
// For local testing, you can use your Account SID and Auth token
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const apiKey = process.env.TWILIO_API_KEY;
const apiSecret = process.env.TWILIO_API_SECRET;
const client = twilio(apiKey, apiSecret, { accountSid: accountSid });

async function createQueryResults() {
  const query = await client.insights.v3.query.create({
    domain: "Conversations",
    query: {
      measures: ["Conversation.Count"],
      dimensions: ["Conversation.ConversationStatus"],
      filters: [
        {
          expressions: [
            {
              op: "GT",
              field: "Conversation.CreatedDate",
              values: ["2026-04-02"],
            },
          ],
        },
      ],
      orderBy: [
        {
          field: "Conversation.Count",
          direction: "DESC",
        },
      ],
    },
  });

  console.log(query.domain);
}

createQueryResults();
```

```python
# Download the helper library from https://www.twilio.com/docs/python/install
import os
from twilio.rest import Client
from twilio.rest.insights.v3 import QueryList

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = os.environ["TWILIO_API_KEY"]
api_secret = os.environ["TWILIO_API_SECRET"]
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
client = Client(api_key, api_secret, account_sid)

query = client.insights.v3.query.create(
    insights_query_request=QueryList.InsightsQueryRequest(
        {
            "domain": "Conversations",
            "query": QueryList.QueryDefinition(
                {
                    "measures": ["Conversation.Count"],
                    "dimensions": ["Conversation.ConversationStatus"],
                    "filters": [
                        QueryList.QueryDefinitionFilters(
                            {
                                "expressions": [
                                    QueryList.QueryDefinitionFiltersExpressions(
                                        {
                                            "op": "GT",
                                            "field": "Conversation.CreatedDate",
                                            "values": ["2026-04-02"],
                                        }
                                    )
                                ]
                            }
                        )
                    ],
                    "orderBy": [
                        QueryList.QueryDefinitionOrderBy(
                            {"field": "Conversation.Count", "direction": "DESC"}
                        )
                    ],
                }
            ),
        }
    )
)

print(query.domain)
```

```csharp
// Install the C# / .NET helper library from twilio.com/docs/csharp/install

using System;
using Twilio;
using Twilio.Rest.Insights.V3;
using System.Threading.Tasks;
using System.Collections.Generic;

class Program {
    public static async Task Main(string[] args) {
        // Find your Account SID at twilio.com/console
        // Provision API Keys at twilio.com/console/runtime/api-keys
        // and set the environment variables. See http://twil.io/secure
        // For local testing, you can use your Account SID and Auth token
        string apiKey = Environment.GetEnvironmentVariable("TWILIO_API_KEY");
        string apiSecret = Environment.GetEnvironmentVariable("TWILIO_API_SECRET");
        string accountSid = Environment.GetEnvironmentVariable("TWILIO_ACCOUNT_SID");

        TwilioClient.Init(apiKey, apiSecret, accountSid);

        var query = await QueryResource.CreateAsync(
            insightsQueryRequest: new QueryResource.InsightsQueryRequest.Builder()
                .WithDomain("Conversations")
                .WithQuery(
                    new QueryResource.QueryDefinition.Builder()
                        .WithMeasures(new List<string> { "Conversation.Count" })
                        .WithDimensions(new List<string> { "Conversation.ConversationStatus" })
                        .WithFilters(new List<QueryResource.QueryDefinitionFilters> {
                            new QueryResource.QueryDefinitionFilters.Builder()
                                .WithExpressions(
                                    new List<QueryResource.QueryDefinitionFiltersExpressions> {
                                        new QueryResource.QueryDefinitionFiltersExpressions
                                            .Builder()
                                            .WithOp("GT")
                                            .WithField("Conversation.CreatedDate")
                                            .WithValues(new List<string> { "2026-04-02" })
                                            .Build()
                                    })
                                .Build()
                        })
                        .WithOrderBy(new List<QueryResource.QueryDefinitionOrderBy> {
                            new QueryResource.QueryDefinitionOrderBy.Builder()
                                .WithField("Conversation.Count")
                                .WithDirection("DESC")
                                .Build()
                        })
                        .Build())
                .Build());

        Console.WriteLine(query.Domain);
    }
}
```

```java
// Install the Java helper library from twilio.com/docs/java/install

import java.util.Arrays;
import java.util.HashMap;
import java.util.Map;
import com.twilio.Twilio;
import com.twilio.rest.insights.v3.Query;

public class Example {
    // Find your Account SID at twilio.com/console
    // Provision API Keys at twilio.com/console/runtime/api-keys
    // and set the environment variables. See http://twil.io/secure
    // For local testing, you can use your Account SID and Auth token
    public static final String API_KEY = System.getenv("TWILIO_API_KEY");
    public static final String API_SECRET = System.getenv("TWILIO_API_SECRET");
    public static final String ACCOUNT_SID = System.getenv("TWILIO_ACCOUNT_SID");

    public static void main(String[] args) {
        Twilio.init(API_KEY, API_SECRET, ACCOUNT_SID);

        Query.QueryDefinitionFiltersExpressions queryDefinitionFiltersExpressions1 =
            Query.QueryDefinitionFiltersExpressions.builder(Query.Op.GT, "Conversation.CreatedDate")
                .values(Arrays.asList("2026-04-02"))
                .build();

        Query.QueryDefinitionFilters queryDefinitionFilters1 =
            Query.QueryDefinitionFilters.builder(Arrays.asList(queryDefinitionFiltersExpressions1)).build();

        Query.QueryDefinitionOrderBy queryDefinitionOrderBy1 =
            Query.QueryDefinitionOrderBy.builder().field("Conversation.Count").direction(Query.Direction.DESC).build();

        Query.QueryDefinition queryDefinition = Query.QueryDefinition.builder()
                                                    .measures(Arrays.asList("Conversation.Count"))
                                                    .dimensions(Arrays.asList("Conversation.ConversationStatus"))
                                                    .filters(Arrays.asList(queryDefinitionFilters1))
                                                    .orderBy(Arrays.asList(queryDefinitionOrderBy1))
                                                    .build();

        Query.InsightsQueryRequest insightsQueryRequest =
            Query.InsightsQueryRequest.builder(queryDefinition).domain("Conversations").build();

        Query.CreateQueryResponse response = Query.creator(insightsQueryRequest).create();

        System.out.println(response.getDomain());
    }
}
```

```ruby
# Download the helper library from https://www.twilio.com/docs/ruby/install
require 'twilio-ruby'

# Find your Account SID at twilio.com/console
# Provision API Keys at twilio.com/console/runtime/api-keys
# and set the environment variables. See http://twil.io/secure
# For local testing, you can use your Account SID and Auth token
api_key = ENV['TWILIO_API_KEY']
api_secret = ENV['TWILIO_API_SECRET']
account_sid = ENV['TWILIO_ACCOUNT_SID']
@client = Twilio::REST::Client.new(api_key, api_secret, account_sid)

query = @client
        .insights
        .v3
        .query
        .create(
          insights_query_request: {
            'domain' => 'Conversations',
            'query' => {
              'measures' => [
                'Conversation.Count'
              ],
              'dimensions' => [
                'Conversation.ConversationStatus'
              ],
              'filters' => [
                {
                  'expressions' => [
                    {
                      'op' => 'GT',
                      'field' => 'Conversation.CreatedDate',
                      'values' => [
                        '2026-04-02'
                      ]
                    }
                  ]
                }
              ],
              'orderBy' => [
                {
                  'field' => 'Conversation.Count',
                  'direction' => 'DESC'
                }
              ]
            }
          }
        )

puts query.domain
```

```bash
INSIGHTS_QUERY_REQUEST_OBJ=$(cat << EOF
{
  "domain": "Conversations",
  "query": {
    "measures": [
      "Conversation.Count"
    ],
    "dimensions": [
      "Conversation.ConversationStatus"
    ],
    "filters": [
      {
        "expressions": [
          {
            "op": "GT",
            "field": "Conversation.CreatedDate",
            "values": [
              "2026-04-02"
            ]
          }
        ]
      }
    ],
    "orderBy": [
      {
        "field": "Conversation.Count",
        "direction": "DESC"
      }
    ]
  }
}
EOF
)
curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query" \
--json "$INSIGHTS_QUERY_REQUEST_OBJ" \
-u $TWILIO_API_KEY:$TWILIO_API_SECRET
```

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.

```bash
curl -X POST "https://insights.twilio.com/v3/InsightsDomains/Conversations/Query?pageSize=20" \
  -u $TWILIO_API_KEY:$TWILIO_API_SECRET \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "Conversations",
    "query": {
      "measures": ["Conversation.Count"],
      "dimensions": ["Conversation.ConversationId"],
      "filters": [
        {
          "expressions": [
            {
              "op": "GT",
              "field": "Conversation.CreatedDate",
              "values": ["2026-04-02"]
            }
          ]
        }
      ]
    }
  }'
```

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

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

## Next steps

Explore the following resources to learn more:

* [Aggregate conversation data](/docs/conversations/intelligence/conversation-insights/aggregate-data)
* [Data model](/docs/conversations/intelligence/conversation-insights/data-model): see all available measures and dimensions.