Vapi Insight API
Define and run Insight queries across call data, including preview-before-save and on-demand runs, to extract structured signals from conversation transcripts.
OpenAPI Specification
openapi: 3.0.0
info:
title: Vapi Insight API
description: Vapi API — Insight resource. Voice AI for developers.
version: '1.0'
contact:
name: Vapi
url: https://vapi.ai
servers:
- url: https://api.vapi.ai
security:
- bearer: []
tags:
- name: Insight
description: Insight endpoints.
paths:
/reporting/insight:
post:
operationId: InsightController_create
summary: Create Insight
parameters: []
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateBarInsightFromCallTableDTO'
title: CreateBarInsightFromCallTableDTO
- $ref: '#/components/schemas/CreatePieInsightFromCallTableDTO'
title: CreatePieInsightFromCallTableDTO
- $ref: '#/components/schemas/CreateLineInsightFromCallTableDTO'
title: CreateLineInsightFromCallTableDTO
- $ref: '#/components/schemas/CreateTextInsightFromCallTableDTO'
title: CreateTextInsightFromCallTableDTO
discriminator:
propertyName: type
mapping:
bar: '#/components/schemas/CreateBarInsightFromCallTableDTO'
pie: '#/components/schemas/CreatePieInsightFromCallTableDTO'
line: '#/components/schemas/CreateLineInsightFromCallTableDTO'
text: '#/components/schemas/CreateTextInsightFromCallTableDTO'
responses:
'201':
description: ''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BarInsight'
- $ref: '#/components/schemas/PieInsight'
- $ref: '#/components/schemas/LineInsight'
- $ref: '#/components/schemas/TextInsight'
discriminator:
propertyName: type
mapping:
bar: '#/components/schemas/BarInsight'
pie: '#/components/schemas/PieInsight'
line: '#/components/schemas/LineInsight'
text: '#/components/schemas/TextInsight'
tags:
- Insight
security:
- bearer: []
get:
operationId: InsightController_findAll
summary: Get Insights
parameters:
- name: id
required: false
in: query
schema:
type: string
- name: page
required: false
in: query
description: This is the page number to return. Defaults to 1.
schema:
minimum: 1
type: number
- name: sortOrder
required: false
in: query
description: This is the sort order for pagination. Defaults to 'DESC'.
schema:
enum:
- ASC
- DESC
type: string
- name: sortBy
required: false
in: query
description: This is the column to sort by. Defaults to 'createdAt'.
schema:
enum:
- createdAt
- duration
- cost
type: string
- name: limit
required: false
in: query
description: This is the maximum number of items to return. Defaults to 100.
schema:
minimum: 0
maximum: 1000
type: number
- name: createdAtGt
required: false
in: query
description: This will return items where the createdAt is greater than the specified value.
schema:
format: date-time
type: string
- name: createdAtLt
required: false
in: query
description: This will return items where the createdAt is less than the specified value.
schema:
format: date-time
type: string
- name: createdAtGe
required: false
in: query
description: This will return items where the createdAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: createdAtLe
required: false
in: query
description: This will return items where the createdAt is less than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtGt
required: false
in: query
description: This will return items where the updatedAt is greater than the specified value.
schema:
format: date-time
type: string
- name: updatedAtLt
required: false
in: query
description: This will return items where the updatedAt is less than the specified value.
schema:
format: date-time
type: string
- name: updatedAtGe
required: false
in: query
description: This will return items where the updatedAt is greater than or equal to the specified value.
schema:
format: date-time
type: string
- name: updatedAtLe
required: false
in: query
description: This will return items where the updatedAt is less than or equal to the specified value.
schema:
format: date-time
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/InsightPaginatedResponse'
tags:
- Insight
security:
- bearer: []
/reporting/insight/{id}:
patch:
operationId: InsightController_update
summary: Update Insight
parameters:
- name: id
required: true
in: path
description: The unique identifier for the resource.
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/UpdateBarInsightFromCallTableDTO'
title: UpdateBarInsightFromCallTableDTO
- $ref: '#/components/schemas/UpdatePieInsightFromCallTableDTO'
title: UpdatePieInsightFromCallTableDTO
- $ref: '#/components/schemas/UpdateLineInsightFromCallTableDTO'
title: UpdateLineInsightFromCallTableDTO
- $ref: '#/components/schemas/UpdateTextInsightFromCallTableDTO'
title: UpdateTextInsightFromCallTableDTO
discriminator:
propertyName: type
mapping:
bar: '#/components/schemas/UpdateBarInsightFromCallTableDTO'
pie: '#/components/schemas/UpdatePieInsightFromCallTableDTO'
line: '#/components/schemas/UpdateLineInsightFromCallTableDTO'
text: '#/components/schemas/UpdateTextInsightFromCallTableDTO'
responses:
'200':
description: ''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BarInsight'
- $ref: '#/components/schemas/PieInsight'
- $ref: '#/components/schemas/LineInsight'
- $ref: '#/components/schemas/TextInsight'
discriminator:
propertyName: type
mapping:
bar: '#/components/schemas/BarInsight'
pie: '#/components/schemas/PieInsight'
line: '#/components/schemas/LineInsight'
text: '#/components/schemas/TextInsight'
tags:
- Insight
security:
- bearer: []
get:
operationId: InsightController_findOne
summary: Get Insight
parameters:
- name: id
required: true
in: path
description: The unique identifier for the resource.
schema:
format: uuid
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BarInsight'
- $ref: '#/components/schemas/PieInsight'
- $ref: '#/components/schemas/LineInsight'
- $ref: '#/components/schemas/TextInsight'
discriminator:
propertyName: type
mapping:
bar: '#/components/schemas/BarInsight'
pie: '#/components/schemas/PieInsight'
line: '#/components/schemas/LineInsight'
text: '#/components/schemas/TextInsight'
tags:
- Insight
security:
- bearer: []
delete:
operationId: InsightController_remove
summary: Delete Insight
parameters:
- name: id
required: true
in: path
description: The unique identifier for the resource.
schema:
format: uuid
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/BarInsight'
- $ref: '#/components/schemas/PieInsight'
- $ref: '#/components/schemas/LineInsight'
- $ref: '#/components/schemas/TextInsight'
discriminator:
propertyName: type
mapping:
bar: '#/components/schemas/BarInsight'
pie: '#/components/schemas/PieInsight'
line: '#/components/schemas/LineInsight'
text: '#/components/schemas/TextInsight'
tags:
- Insight
security:
- bearer: []
/reporting/insight/{id}/run:
post:
operationId: InsightController_run
summary: Run Insight
parameters:
- name: id
required: true
in: path
description: The unique identifier for the resource.
schema:
format: uuid
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/InsightRunDTO'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/InsightRunResponse'
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/InsightRunResponse'
tags:
- Insight
security:
- bearer: []
/reporting/insight/preview:
post:
operationId: InsightController_preview
summary: Preview Insight
parameters: []
requestBody:
required: true
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/CreateBarInsightFromCallTableDTO'
title: CreateBarInsightFromCallTableDTO
- $ref: '#/components/schemas/CreatePieInsightFromCallTableDTO'
title: CreatePieInsightFromCallTableDTO
- $ref: '#/components/schemas/CreateLineInsightFromCallTableDTO'
title: CreateLineInsightFromCallTableDTO
- $ref: '#/components/schemas/CreateTextInsightFromCallTableDTO'
title: CreateTextInsightFromCallTableDTO
discriminator:
propertyName: type
mapping:
bar: '#/components/schemas/CreateBarInsightFromCallTableDTO'
pie: '#/components/schemas/CreatePieInsightFromCallTableDTO'
line: '#/components/schemas/CreateLineInsightFromCallTableDTO'
text: '#/components/schemas/CreateTextInsightFromCallTableDTO'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/InsightRunResponse'
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/InsightRunResponse'
tags:
- Insight
security:
- bearer: []
components:
securitySchemes:
bearer:
scheme: bearer
bearerFormat: Bearer
type: http
description: Retrieve your API Key from [Dashboard](dashboard.vapi.ai).
schemas:
BarInsight:
type: object
properties:
name:
type: string
description: This is the name of the Insight.
minLength: 1
maxLength: 255
type:
type: string
description: 'This is the type of the Insight.
It is required to be `bar` to create a bar insight.'
enum:
- bar
formulas:
type: array
description: 'Formulas are mathematical expressions applied on the data returned by the queries to transform them
before being used to create the insight.
The formulas needs to be a valid mathematical expression, supported by MathJS - https://mathjs.org/docs/expressions/syntax.html
A formula is created by using the query names as the variable.
The formulas must contain at least one query name in the LiquidJS format {{query_name}} or {{[''query name'']}}
which will be substituted with the query result.
For example, if you have 2 queries, ''Was Booking Made'' and ''Average Call Duration'', you can create a formula
like this:
```
{{[''Query 1'']}} / {{[''Query 2'']}} * 100
```
```
({{[Query 1]}} * 10) + {{[Query 2]}}
```
This will take the
You can also use the query names as the variable in the formula.'
items:
$ref: '#/components/schemas/InsightFormula'
metadata:
description: This is the metadata for the insight.
allOf:
- $ref: '#/components/schemas/BarInsightMetadata'
timeRange:
$ref: '#/components/schemas/InsightTimeRangeWithStep'
groupBy:
type: string
description: 'This is the group by column for the insight when table is `call`.
These are the columns to group the results by.
All results are grouped by the time range step by default.'
example:
- assistant_id
enum:
- assistantId
- workflowId
- squadId
- phoneNumberId
- type
- endedReason
- customerNumber
- campaignId
- artifact.structuredOutputs[OutputID]
queries:
type: array
description: These are the queries to run to generate the insight.
items:
oneOf:
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStringTypeColumn'
title: JSONQueryOnCallTableWithStringTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithNumberTypeColumn'
title: JSONQueryOnCallTableWithNumberTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStructuredOutputColumn'
title: JSONQueryOnCallTableWithStructuredOutputColumn
- $ref: '#/components/schemas/JSONQueryOnEventsTable'
title: JSONQueryOnEventsTable
id:
type: string
description: This is the unique identifier for the Insight.
orgId:
type: string
description: This is the unique identifier for the org that this Insight belongs to.
createdAt:
format: date-time
type: string
description: This is the ISO 8601 date-time string of when the Insight was created.
updatedAt:
format: date-time
type: string
description: This is the ISO 8601 date-time string of when the Insight was last updated.
systemKey:
type: string
description: Stable server-owned identifier for system-created insights.
required:
- type
- queries
- id
- orgId
- createdAt
- updatedAt
BarInsightMetadata:
type: object
properties:
xAxisLabel:
type: string
minLength: 1
maxLength: 40
yAxisLabel:
type: string
minLength: 1
maxLength: 40
yAxisMin:
type: number
yAxisMax:
type: number
name:
type: string
minLength: 1
maxLength: 255
CreateBarInsightFromCallTableDTO:
type: object
properties:
name:
type: string
description: This is the name of the Insight.
minLength: 1
maxLength: 255
type:
type: string
description: 'This is the type of the Insight.
It is required to be `bar` to create a bar insight.'
enum:
- bar
formulas:
type: array
description: 'Formulas are mathematical expressions applied on the data returned by the queries to transform them
before being used to create the insight.
The formulas needs to be a valid mathematical expression, supported by MathJS - https://mathjs.org/docs/expressions/syntax.html
A formula is created by using the query names as the variable.
The formulas must contain at least one query name in the LiquidJS format {{query_name}} or {{[''query name'']}}
which will be substituted with the query result.
For example, if you have 2 queries, ''Was Booking Made'' and ''Average Call Duration'', you can create a formula
like this:
```
{{[''Query 1'']}} / {{[''Query 2'']}} * 100
```
```
({{[Query 1]}} * 10) + {{[Query 2]}}
```
This will take the
You can also use the query names as the variable in the formula.'
items:
$ref: '#/components/schemas/InsightFormula'
metadata:
description: This is the metadata for the insight.
allOf:
- $ref: '#/components/schemas/BarInsightMetadata'
timeRange:
$ref: '#/components/schemas/InsightTimeRangeWithStep'
groupBy:
type: string
description: 'This is the group by column for the insight when table is `call`.
These are the columns to group the results by.
All results are grouped by the time range step by default.'
example:
- assistant_id
enum:
- assistantId
- workflowId
- squadId
- phoneNumberId
- type
- endedReason
- customerNumber
- campaignId
- artifact.structuredOutputs[OutputID]
queries:
type: array
description: These are the queries to run to generate the insight.
items:
oneOf:
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStringTypeColumn'
title: JSONQueryOnCallTableWithStringTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithNumberTypeColumn'
title: JSONQueryOnCallTableWithNumberTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStructuredOutputColumn'
title: JSONQueryOnCallTableWithStructuredOutputColumn
- $ref: '#/components/schemas/JSONQueryOnEventsTable'
title: JSONQueryOnEventsTable
required:
- type
- queries
CreateLineInsightFromCallTableDTO:
type: object
properties:
name:
type: string
description: This is the name of the Insight.
minLength: 1
maxLength: 255
type:
type: string
description: 'This is the type of the Insight.
It is required to be `line` to create a line insight.'
enum:
- line
formulas:
type: array
description: 'Formulas are mathematical expressions applied on the data returned by the queries to transform them
before being used to create the insight.
The formulas needs to be a valid mathematical expression, supported by MathJS - https://mathjs.org/docs/expressions/syntax.html
A formula is created by using the query names as the variable.
The formulas must contain at least one query name in the LiquidJS format {{query_name}} or {{[''query name'']}}
which will be substituted with the query result.
For example, if you have 2 queries, ''Was Booking Made'' and ''Average Call Duration'', you can create a formula
like this:
```
{{[''Query 1'']}} / {{[''Query 2'']}} * 100
```
```
({{[Query 1]}} * 10) + {{[Query 2]}}
```
This will take the
You can also use the query names as the variable in the formula.'
items:
$ref: '#/components/schemas/InsightFormula'
metadata:
description: This is the metadata for the insight.
allOf:
- $ref: '#/components/schemas/LineInsightMetadata'
timeRange:
$ref: '#/components/schemas/InsightTimeRangeWithStep'
groupBy:
type: string
description: 'This is the group by column for the insight when table is `call`.
These are the columns to group the results by.
All results are grouped by the time range step by default.'
example:
- assistant_id
enum:
- assistantId
- workflowId
- squadId
- phoneNumberId
- type
- endedReason
- customerNumber
- campaignId
- artifact.structuredOutputs[OutputID]
queries:
type: array
description: These are the queries to run to generate the insight.
items:
oneOf:
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStringTypeColumn'
title: JSONQueryOnCallTableWithStringTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithNumberTypeColumn'
title: JSONQueryOnCallTableWithNumberTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStructuredOutputColumn'
title: JSONQueryOnCallTableWithStructuredOutputColumn
required:
- type
- queries
CreatePieInsightFromCallTableDTO:
type: object
properties:
name:
type: string
description: This is the name of the Insight.
minLength: 1
maxLength: 255
type:
type: string
description: 'This is the type of the Insight.
It is required to be `pie` to create a pie insight.'
enum:
- pie
formulas:
type: array
description: 'Formulas are mathematical expressions applied on the data returned by the queries to transform them
before being used to create the insight.
The formulas needs to be a valid mathematical expression, supported by MathJS - https://mathjs.org/docs/expressions/syntax.html
A formula is created by using the query names as the variable.
The formulas must contain at least one query name in the LiquidJS format {{query_name}} or {{[''query name'']}}
which will be substituted with the query result.
For example, if you have 2 queries, ''Was Booking Made'' and ''Average Call Duration'', you can create a formula
like this:
```
{{[''Query 1'']}} / {{[''Query 2'']}} * 100
```
```
({{[Query 1]}} * 10) + {{[Query 2]}}
```
This will take the
You can also use the query names as the variable in the formula.'
items:
$ref: '#/components/schemas/InsightFormula'
timeRange:
$ref: '#/components/schemas/InsightTimeRange'
groupBy:
type: string
description: 'This is the group by column for the insight when table is `call`.
These are the columns to group the results by.
All results are grouped by the time range step by default.'
example:
- assistant_id
enum:
- assistantId
- workflowId
- squadId
- phoneNumberId
- type
- endedReason
- customerNumber
- campaignId
- artifact.structuredOutputs[OutputID]
queries:
type: array
description: These are the queries to run to generate the insight.
items:
oneOf:
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStringTypeColumn'
title: JSONQueryOnCallTableWithStringTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithNumberTypeColumn'
title: JSONQueryOnCallTableWithNumberTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStructuredOutputColumn'
title: JSONQueryOnCallTableWithStructuredOutputColumn
required:
- type
- queries
CreateTextInsightFromCallTableDTO:
type: object
properties:
name:
type: string
description: This is the name of the Insight.
minLength: 1
maxLength: 255
type:
type: string
description: 'This is the type of the Insight.
It is required to be `text` to create a text insight.'
enum:
- text
formula:
type: object
description: 'Formulas are mathematical expressions applied on the data returned by the queries to transform them
before being used to create the insight.
The formulas needs to be a valid mathematical expression, supported by MathJS - https://mathjs.org/docs/expressions/syntax.html
A formula is created by using the query names as the variable.
The formulas must contain at least one query name in the LiquidJS format {{query_name}} or {{[''query name'']}}
which will be substituted with the query result.
For example, if you have 2 queries, ''Was Booking Made'' and ''Average Call Duration'', you can create a formula
like this:
```
{{[''Query 1'']}} / {{[''Query 2'']}} * 100
```
```
({{[Query 1]}} * 10) + {{[Query 2]}}
```
This will take the
You can also use the query names as the variable in the formula.'
items:
$ref: '#/components/schemas/InsightFormula'
timeRange:
$ref: '#/components/schemas/InsightTimeRange'
queries:
type: array
description: 'These are the queries to run to generate the insight.
For Text Insights, we only allow a single query, or require a formula if multiple queries are provided'
items:
oneOf:
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStringTypeColumn'
title: JSONQueryOnCallTableWithStringTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithNumberTypeColumn'
title: JSONQueryOnCallTableWithNumberTypeColumn
- $ref: '#/components/schemas/JSONQueryOnCallTableWithStructuredOutputColumn'
title: JSONQueryOnCallTableWithStructuredOutputColumn
required:
- type
- queries
EventsTableBooleanCondition:
type: object
properties:
column:
type: string
description: The boolean field name from the event data
example: success
operator:
type: string
description: Boolean comparison operator
example: '='
enum:
- '='
value:
type: boolean
description: The boolean value to compare
example: true
required:
- column
- operator
- value
EventsTableNumberCondition:
type: object
properties:
column:
type: string
description: The number field name from the event data
example: latency
operator:
type: string
description: Number comparison operator
example: '>='
enum:
- '='
- '!='
- '>'
- '>='
- <
- <=
value:
type: number
description: The number value to compare
example: 1000
required:
- column
- operator
- value
EventsTableStringCondition:
type: object
properties:
column:
type: string
description: The string field name from the event data
example: provider
operator:
type: string
description: String comparison operator
example: '='
enum:
- '='
- '!='
- contains
- notContains
value:
type: string
description: The string value to compare
example: openai
required:
- column
- operator
- value
FilterDateTypeColumnOnCallTable:
type: object
properties:
column:
type: string
description: 'This is the column in the call table that will be filtered on.
Date Type columns are columns where the rows store data as a date.
Must be a valid column for the selected table.'
example: created_at
enum:
- startedAt
- endedAt
operator:
type: string
description: 'This is the operator to use for the filter.
For date type columns, the operator must be "=", ">", "<", ">=", "<="'
example: '"=" or ">" or "<" or ">=" or "<="'
enum:
- '='
- '!='
- '>'
- <
- '>='
- <=
value:
type: string
description: 'This is the value to filter on.
Must be a valid ISO 8601 date-time string.'
example: '2025-01-01T00:00:00Z'
required:
- column
- operator
- value
FilterNumberArrayTypeColumnOnCallTable:
type: object
properties:
column:
type: string
description: 'This is the column in the call table that will be filtered on.
Number Array Type columns are the same as Number Type columns, but provides the ability to filter on multiple
values provided as an array.
Must be a valid column for the selected table.'
example: duration
enum:
- duration
- cost
- averageModelLatency
- averageVoiceLatency
- averageTranscriberLatency
- averageTurnLatency
- averageEndpointingLatency
operator:
type: string
description: 'This is the operator to use for the filter.
The operator must be `in` or `not_in`.'
example: '"in" or "not_in"'
enum:
- in
- not_in
- is_empty
- is_not_empty
value:
description: This is the value to filter on.
type: array
items:
type: number
required:
- column
- operator
- value
FilterNumberTypeColumnOnCallTable:
type: object
properties:
column:
type: string
description: 'This is the column in the call table that will be filtered on.
Number Type columns are columns where the rows store data as a number.
Must be a valid column for the selected table.'
example: duration
enum:
- duration
- cost
- averageModelLatency
- averageVoiceLatency
- averageTranscriberLatency
- averageTurnLatency
- averageEndpointingLatency
operator:
type: string
description: 'This is the operator to
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vapi-ai/refs/heads/main/openapi/vapi-insight-api-openapi.yml