Skip to content Skip to navigation Skip to topbar

Submit an asynchronous query

(new)

Public beta

Conversation Insights, including the APIs, is currently available as a public beta release and the information contained in this document is subject to change. Some features are not yet implemented and others may be changed before the product is declared as generally available. Public beta products are not covered by the Twilio Support Terms or Twilio Service Level Agreement.

Conversation Insights is not PCI compliant or a HIPAA Eligible Service and should not be used in workflows that are subject to HIPAA or PCI.

Conversations products are only available in the new Twilio Console. If your account hasn't been migrated, you'll be redirected to the legacy Console where these products won't appear.

POST/v3/InsightsDomains/Conversations/QueryJobs

Base url: https://insights.twilio.com (base url)

Submit a long-running semantic query against the Conversations domain. Returns 202 Accepted with an operationId and a Location header pointing to the QueryJobs status endpoint for polling.

Request

Authentication

Basic Auth

Headers

Property nameTypeRequiredPIIDescription

idempotency-Keystring<uuid>

Optional

A client-generated UUIDv7 key that ensures idempotent behavior. Submitting the same key with an identical request returns the same operation without re-execution. Scoped to Account + Region. Retained for 24 hours.

Example: 01890a5d-aa0f-7c80-b8e6-0242ac140004

Request body

Encoding type:application/json

Schema

Property nameTypeRequiredPIIDescriptionChild properties

domainstring

Optional

The business domain to execute the query against

Example: Conversations

queryobject

required

Structured query definition that specifies what data to retrieve and how to filter, group, and order it

Show query properties

Responses

202400422429500

Async query accepted

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

operationIdstring<Proc_JobTtid>

Optional

The unique identifier for the asynchronous query operation, in TTID format.

Example: proc_job_01h9d8r0vte3hz8tykdj329t7r

statusenum<string>

Optional

The valid status values for long-running operations.

Possible values:

PENDINGRUNNINGCANCELLEDCOMPLETEDFAILED

statusUrlstring<uri>

Optional

The URI to poll for operation status.

Example: https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r

createdAtstring<date-time>

Optional

The time when the operation was accepted, in RFC 3339 UTC format.

Example: 2026-05-25T14:30:00Z

Bad request

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Unprocessable content (idempotency key payload mismatch)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Too Many requests (rate limit exceeded for request originating from public API)

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Internal server error

Schema

Property nameTypeRequiredPIIDescriptionChild properties

codeinteger<int32>

Optional

Twilio-specific error code

messagestring

Optional

A human readable error message

httpStatusCodeinteger<int32>

Optional

HTTP response status code

userErrorboolean

Optional

Whether the error is a user error (true) or a system error (false)

paramsobject

Optional

A map of parameters related to the error, for example, a params.twilioErrorCodeUrl might hold a URL or link to additional information

Show params properties

Submit an asynchronous query

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 and Auth Token at twilio.com/console
5// and set the environment variables. See http://twil.io/secure
6const accountSid = process.env.TWILIO_ACCOUNT_SID;
7const authToken = process.env.TWILIO_AUTH_TOKEN;
8const client = twilio(accountSid, authToken);
9
10async function createQueryJob() {
11  const queryJob = await client.insights.v3.queryJobs.create({
12    query: {
13      measures: ["measures"],
14      dimensions: ["dimensions"],
15      filters: [
16        {
17          op: "AND",
18          expressions: [
19            {
20              op: "IN",
21              field: "field",
22              values: ["values"],
23            },
24          ],
25        },
26      ],
27      orderBy: [
28        {
29          field: "field",
30          direction: "DESC",
31        },
32      ],
33    },
34  });
35
36  console.log(queryJob.operationId);
37}
38
39createQueryJob();

Response

1{
2  "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r",
3  "status": "PENDING",
4  "statusUrl": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r",
5  "createdAt": "2026-05-25T14:30:00Z"
6}