openapi: 3.2.0 info: title: Twilio - Insights Twilio Insights API description: 'The Twilio Insights v3 API provides semantic query access to Conversations analytics data. Resources include synchronous Query, Metadata, and asynchronous QueryJobs for long-running queries.' termsOfService: https://www.twilio.com/legal/tos contact: name: Twilio Support url: https://support.twilio.com email: support@twilio.com license: name: Apache 2.0 url: https://www.apache.org/licenses/LICENSE-2.0.html version: 1.1.0 x-twilio: apiStandards: v1.0 servers: - url: https://insights.twilio.com security: - basic_apikey_or_accountsid: [] tags: - name: TwilioInsights description: Twilio Insights synchronous Query and Metadata resources. paths: /v3/InsightsDomains/Conversations/Query: servers: - url: https://insights.twilio.com post: summary: Execute a synchronous semantic query description: 'Execute a semantic query against the Conversations domain. Returns results inline. For long-running queries, use the QueryJobs endpoint.' tags: - TwilioInsights operationId: CreateQueryResults parameters: - name: pageSize in: query description: Number of items per page required: false schema: type: integer minimum: 1 example: 20 format: int32 requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InsightsQueryRequest' responses: '200': description: Successful query response content: application/json: schema: $ref: '#/components/schemas/InsightsQueryResponse' 400: description: Bad request content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode 429: description: Too Many requests (rate limit exceeded for request originating from public API) headers: X-RateLimit-Limit: description: Maximum number of requests allowed in the time window schema: type: integer example: 5 X-RateLimit-Remaining: description: Number of requests remaining in the current time window schema: type: integer example: 0 X-RateLimit-Reset: description: Time in seconds until the rate limit resets schema: type: integer example: 45 X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Config: $ref: '#/components/headers/X-Rate-Limit-Config' content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode 500: description: Internal server error content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode security: - basic_apikey_or_accountsid: [] get: summary: Retrieve paginated query results description: Retrieve subsequent pages of a synchronous query using a page token. tags: - TwilioInsights operationId: FetchQueryResults parameters: - name: pageToken in: query description: Pagination token required: true schema: type: string example: eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0= responses: '200': description: Successful query response content: application/json: schema: $ref: '#/components/schemas/InsightsQueryResponse' 400: description: Bad request content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode 429: description: Too Many requests (rate limit exceeded for request originating from public API) headers: X-RateLimit-Limit: description: Maximum number of requests allowed in the time window schema: type: integer example: 5 X-RateLimit-Remaining: description: Number of requests remaining in the current time window schema: type: integer example: 0 X-RateLimit-Reset: description: Time in seconds until the rate limit resets schema: type: integer example: 45 X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Config: $ref: '#/components/headers/X-Rate-Limit-Config' content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode 500: description: Internal server error content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode security: - basic_apikey_or_accountsid: [] /v3/InsightsDomains/Conversations/Metadata: servers: - url: https://insights.twilio.com get: summary: Retrieve domain metadata description: Returns available cubes, measures, and dimensions for the Conversations domain. tags: - TwilioInsights operationId: FetchMetadata responses: '200': description: successful operation content: application/json: schema: $ref: '#/components/schemas/InsightsMetadataResponse' 400: description: Bad request content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode 429: description: Too Many requests (rate limit exceeded for request originating from public API) headers: X-RateLimit-Limit: description: Maximum number of requests allowed in the time window schema: type: integer example: 5 X-RateLimit-Remaining: description: Number of requests remaining in the current time window schema: type: integer example: 0 X-RateLimit-Reset: description: Time in seconds until the rate limit resets schema: type: integer example: 45 X-Rate-Limit-Limit: $ref: '#/components/headers/X-Rate-Limit-Limit' X-Rate-Limit-Remaining: $ref: '#/components/headers/X-Rate-Limit-Remaining' X-Rate-Limit-Config: $ref: '#/components/headers/X-Rate-Limit-Config' content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode 500: description: Internal server error content: application/json: schema: type: object properties: code: description: Twilio-specific error code type: integer format: int32 message: description: A human readable error message type: string httpStatusCode: description: HTTP response status code type: integer format: int32 userError: description: Whether the error is a user error (true) or a system error (false) type: boolean params: description: A map of parameters related to the error, for example, a `params.twilioErrorCodeUrl` might hold a URL or link to additional information type: object additionalProperties: type: string required: - code - message - httpStatusCode security: - basic_apikey_or_accountsid: [] components: headers: X-Rate-Limit-Remaining: schema: type: string X-Rate-Limit-Limit: schema: type: string X-Rate-Limit-Config: schema: type: string schemas: InsightsQueryResponse: type: object properties: domain: type: string example: Insights description: Indicates the business domain the query was executed against items: type: array description: Array of result objects containing the query results. Each object contains properties matching the requested measures and dimensions. items: type: object description: Query result object with dynamic properties based on requested measures and dimensions. additionalProperties: description: Dynamic property values based on requested measures and dimensions. example: - Id: conv1 Languages: - en Channels: - voice OperatorResult.Value: positive - Id: conv2 Languages: - en - es Channels: - chat OperatorResult.Value: negative meta: $ref: '#/components/schemas/PaginationMeta' QueryDefinition: type: object description: Structured query definition that specifies what data to retrieve and how to filter, group, and order it properties: measures: type: array description: Array of measures to retrieve, representing quantitative values or metrics to be calculated items: type: string example: - OperatorResult.Count dimensions: type: array description: Array of dimensions to retrieve, representing categorical attributes for grouping and organizing data items: type: string example: - DateCreated - OperatorResults filters: type: array description: Nested filter conditions. Always use `op` and `expressions`. items: type: object required: - expressions properties: op: type: string enum: - AND - OR - EQ - NE - GT - LT - IN example: AND expressions: type: array items: type: object required: - op - field properties: op: type: string enum: - AND - OR - EQ - NE - GT - LT - IN example: IN field: type: string example: OperatorResult.Value values: type: array items: type: string example: - positive - negative orderBy: type: array description: Specifications for sorting the query results by specific fields in ascending or descending order items: type: object properties: field: type: string description: Dimension or measure to order by example: OperatorResults.CreatedDate direction: type: string description: Sort order direction, ascending or descending enum: - ASC - DESC example: DESC InsightsQueryRequest: type: object required: - query properties: domain: type: string example: Conversations description: The business domain to execute the query against query: $ref: '#/components/schemas/QueryDefinition' InsightsMetadataResponse: type: object description: Response containing metadata about available cubes, measures, and dimensions for a domain properties: domain: type: string example: Insights description: The business domain name for which metadata is being provided cubes: type: array description: List of data cubes available in the domain, each containing measures and dimensions items: type: object required: - name - measures - dimensions properties: name: type: string description: Name of the cube, used as a reference in queries description: type: string description: Human-readable description of what the cube represents measures: type: array description: List of measures available in the cube, representing quantitative values that can be aggregated items: type: object required: - name - type properties: name: type: string description: Identifier used to reference this measure in queries description: type: string description: Detailed explanation of what this measure represents type: type: string description: Type of the measure aggregation: type: string description: Aggregation type for the measure (e.g., sum, count, average) dimensions: type: array description: List of dimensions available in the cube, representing categorical attributes for grouping data items: type: object required: - name - type properties: name: type: string description: Identifier used to reference this dimension in queries description: type: string description: Detailed explanation of what this dimension represents type: type: string description: Data type of the dimension (e.g., string, number, boolean, date) PaginationMeta: type: object description: 'The pagination metadata containing navigation tokens and result information. By convention, this schema should be added to the response payload''s ''meta'' attribute. ' required: - key - pageSize properties: key: type: string description: 'The key of the list property contains the actual data items. This enables programmatic iteration over paginated results. ' example: items pageSize: type: integer description: 'The actual number of items returned in this response. May be less than the requested pageSize for the last page. ' example: 20 previousToken: type: - string - 'null' description: 'Token to fetch the previous page of results. Only included if there is a previous page, otherwise omitted. ' example: eyJwYWdlIjowLCJxdWVyeSI6ImJvb2tzIn0= nextToken: type: - string - 'null' description: 'Token to fetch the next page of results. Only included if there is a next page, otherwise omitted. ' example: eyJwYWdlIjoyLCJxdWVyeSI6ImJvb2tzIn0= securitySchemes: basic_apikey_or_accountsid: scheme: basic type: http description: This API uses [basic authentication](https://www.twilio.com/docs/glossary/what-is-basic-authentication). Use an [API key](https://www.twilio.com/docs/iam/api-keys) as the username and the API key secret as the password. You can also use your account SID and auth token, but limit their use to local testing.