Skip to content Skip to navigation Skip to topbar

Retrieve a list of asynchronous queries

(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.

GET/v3/InsightsDomains/Conversations/QueryJobs

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

Returns a paginated list of asynchronous query operations for the authenticated account. Optionally filter by status.

Request

Authentication

Basic Auth

Query string

Property nameTypeRequiredPIIDescription

pageSizeinteger

Optional

The maximum number of resources to return

Default: 50Minimum: 1Maximum: 1000

pageTokenstring

Optional

Token for pagination

statusenum<string>

Optional

The operation status to filter results by.

Possible values:

PENDINGRUNNINGCANCELLEDCOMPLETEDFAILED

Responses

200400429500

Paginated list of async query operations

SchemaExample

Property nameTypeRequiredPIIDescriptionChild properties

itemsarray[object]

Optional

Show items properties

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

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

createdAtstring<date-time>

Optional

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

completedAtstring<date-time>

Optional

The time when the operation reached a terminal state (CANCELLED, COMPLETED, or FAILED), in RFC 3339 UTC format. Null while the operation is still PENDING or RUNNING.

Example: 2026-05-25T14:32:17Z

errorobject

Optional

The error details, present only when status is FAILED.

Show error properties

resultUrlstring<uri>

Optional

The URL to retrieve query results, present only when status is COMPLETED. Supports pagination via the pageSize and pageToken query parameters.

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

resultIdstring

Optional

The identifier of the results resource, present only when status is COMPLETED. Equal to operationId, since results are keyed by the operation ID.

Example: proc_job_01h9d8r0vte3hz8tykdj329t7r

resultRetentionPeriodstring<duration>

Optional

The duration for how long results are retained, in ISO 8601 format.

Example: P7D

metaobject

Optional

The pagination metadata containing navigation tokens and result information. By convention, this schema should be added to the response payload's 'meta' attribute.

Show meta properties

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

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

Retrieve a list of asynchronous queries

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 listQueryJobs() {
11  const queryJobs = await client.insights.v3.queryJobs.list({ limit: 20 });
12
13  queryJobs.forEach((q) => console.log(q.operationId));
14}
15
16listQueryJobs();

Response

1{
2  "items": [
3    {
4      "operationId": "proc_job_01h9d8r0vte3hz8tykdj329t7r",
5      "status": "RUNNING",
6      "createdAt": "2026-05-25T14:30:00Z",
7      "statusUrl": "https://insights.twilio.com/v3/InsightsDomains/Conversations/QueryJobs/proc_job_01h9d8r0vte3hz8tykdj329t7r",
8      "resultId": "proc_job_01h9d8r0vte3hz8tykdj329t7r"
9    }
10  ],
11  "meta": {
12    "key": "items",
13    "pageSize": 1
14  }
15}