Twilio Twilio Insights API

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.