Vapi Insight API
The Insight API from Vapi — 4 operation(s) for insight.
OpenAPI Specification
openapi: 3.0.0
info:
title: Vapi Analytics Insight API
description: Voice AI for developers.
version: '1.0'
contact: {}
servers:
- url: https://api.vapi.ai
tags:
- name: Insight
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
schema:
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
schema:
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
schema:
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
schema:
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:
schemas:
LineInsight:
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
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
JSONQueryOnCallTableWithStructuredOutputColumn:
type: object
properties:
type:
type: string
description: This is the type of query. Only allowed type is "vapiql-json".
example: vapiql-json
enum:
- vapiql-json
table:
type: string
description: This is the table that will be queried.
enum:
- call
filters:
type: array
description: 'This is the filters to apply to the insight.
The discriminator automatically selects the correct filter type based on column and operator.'
items:
oneOf:
- $ref: '#/components/schemas/FilterStringTypeColumnOnCallTable'
- $ref: '#/components/schemas/FilterStringArrayTypeColumnOnCallTable'
- $ref: '#/components/schemas/FilterNumberTypeColumnOnCallTable'
- $ref: '#/components/schemas/FilterNumberArrayTypeColumnOnCallTable'
- $ref: '#/components/schemas/FilterDateTypeColumnOnCallTable'
- $ref: '#/components/schemas/FilterStructuredOutputColumnOnCallTable'
column:
type: string
enum:
- artifact.structuredOutputs[OutputID]
description: 'This is the column that will be queried in the call table.
Structured Output Type columns are only to query on artifact.structuredOutputs[OutputID] column.'
example: artifact.structuredOutputs[OutputID]
operation:
type: string
enum:
- average
- count
- sum
- min
- max
description: 'This is the aggregation operation to perform on the column.
When the column is a structured output type, the operation depends on the value of the structured output.
If the structured output is a string or boolean, the operation must be "count".
If the structured output is a number, the operation can be "average", "sum", "min", or "max".'
example: count
name:
type: string
description: 'This is the name of the query.
It will be used to label the query in the insight board on the UI.'
example: Total Calls
required:
- type
- table
- column
- operation
UpdateTextInsightFromCallTableDTO:
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
InsightRunResponse:
type: object
properties:
id:
type: string
insightId:
type: string
orgId:
type: string
createdAt:
format: date-time
type: string
updatedAt:
format: date-time
type: string
required:
- id
- insightId
- orgId
- createdAt
- updatedAt
PieInsight:
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
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
Insight:
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.
enum:
- bar
- line
- pie
- text
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
- id
- orgId
- createdAt
- updatedAt
TextInsight:
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
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
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
InsightTimeRange:
type: object
properties:
start:
type: object
description: 'This is the start date for the time range.
Should be a valid ISO 8601 date-time string or relative time string.
If not provided, defaults to the 7 days ago.
Relative time strings of the format "-{number}{unit}" are allowed.
Valid units are:
- d: days
- h: hours
- w: weeks
- m: months
- y: years'
example: '"2025-01-01" or "-7d" or "now"'
end:
type: object
description: 'This is the end date for the time range.
Should be a valid ISO 8601 date-time string or relative time string.
If not provided, defaults to now.
Relative time strings of the format "-{number}{unit}" are allowed.
Valid units are:
- d: days
- h: hours
- w: weeks
- m: months
- y: years'
example: '"2025-01-01" or "now"'
timezone:
type: string
description: 'This is the timezone you want to set for the query.
If not provided, defaults to UTC.'
JSONQueryOnEventsTable:
type: object
properties:
type:
type: string
description: This is the type of query. Only allowed type is "vapiql-json".
example: vapiql-json
enum:
- vapiql-json
table:
type: string
description: 'This is the table that will be queried.
Must be "events" for event-based insights.'
enum:
- events
'on':
type: string
description: The event type to query
example: assistant.model.requestFailed
enum:
- call.started
- call.ended
- call.inProgress
- call.queued
- call.transportConnected
- call.transportDisconnected
- call.transportReconnected
- call.transferInitiated
- call.transferCompleted
- call.transferFailed
- call.transferCancelled
- call.handoffInitiated
- call.handoffCompleted
- call.handoffFailed
- call.assistantSwapped
- call.assistantStarted
- call.customerJoined
- call.customerLeft
- call.controlReceived
- call.listenStarted
- call.recordingStarted
- call.recordingPaused
- call.recordingResumed
- call.voicemailDetected
- call.voicemailNotDetected
- call.dtmfReceived
- call.dtmfSent
- call.amdDetected
- call.hookTriggered
- call.hookSucceeded
- call.hookFailed
- call.statusReceived
- call.silenceTimeout
- call.microphoneTimeout
- call.maxDurationReached
- assistant.voice.requestStarted
- assistant.voice.requestSucceeded
- assistant.voice.requestFailed
- assistant.voice.connectionOpened
- assistant.voice.connectionClosed
- assistant.voice.firstAudioReceived
- assistant.voice.audioChunkReceived
- assistant.voice.generationSucceeded
- assistant.voice.generationFailed
- assistant.voice.textPushed
- assistant.voice.reconnecting
- assistant.voice.cleanup
- assistant.voice.clearing
- assistant.voice.voiceSwitched
- assistant.model.requestStarted
- assista
# --- truncated at 32 KB (76 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vapi/refs/heads/main/openapi/vapi-insight-api-openapi.yml