> ## Documentation Index
> Fetch the complete documentation index at: https://docs.instaview.sk/llms.txt
> Use this file to discover all available pages before exploring further.
# List Conversations
> Lists conversations within the API key's company. Every filter is optional: pass `contactId` to narrow the page to one contact (`candidateId` is accepted as its legacy alias), and omit it to list all of them.
`GET /interviews` is a permanent alias of this endpoint and keeps working unchanged, with the same scopes and the same response. See [Resource names](/api-reference/introduction#resource-names).
Lists conversations with pagination and filtering.
## Overview
This endpoint returns the conversations in your API key's company — useful for showing someone's call history, following a conversation's status, and picking up analysis or analytics once a call has finished.
## Filters
Every filter is optional; omit them all and you get the whole company's conversations, newest first.
| Query parameter | Filters on |
| --------------- | -------------------------------------------------------------------- |
| `contactId` | One contact. `candidateId` is accepted as its permanent legacy alias |
| `agentId` | One agent |
| `jobId` | The job the conversation itself is for (deprecated) |
| `status` | One [status](#status-filtering) |
## Use Cases
* **Call history**: every conversation for one contact
* **Status tracking**: follow progress and completion
* **Results retrieval**: reach analysis, analytics and transcripts
* **Pipeline management**: track conversations across your own process
## Basic Usage
```javascript theme={null}
// List all conversations for a contact
GET /conversations?contactId=contact-uuid
```
## With Pagination
```javascript theme={null}
// Get first page with 20 items
GET /conversations?contactId=contact-uuid&page=1&limit=20
// Get second page
GET /conversations?contactId=contact-uuid&page=2&limit=20
```
## Status Filtering
`status` takes one of `SCHEDULED`, `IN_PROGRESS`, `COMPLETED`, `CANCELLED`, `FAILED`,
`UNREACHABLE` or `UNDEFINED`. The values are upper-case, and anything else is rejected with
`400 Bad Request` before the listing runs.
```javascript theme={null}
// Get only completed conversations
GET /conversations?contactId=contact-uuid&status=COMPLETED
```
## Response Structure
Each row carries the conversation's own fields, plus analysis when there is any:
```json theme={null}
{
"data": [
{
"id": "conversation-uuid",
"contactId": "contact-uuid",
"candidateId": "contact-uuid",
"agentId": "agent-uuid",
"status": "COMPLETED",
"analysis": {
"id": "analysis-uuid",
"general": {
"overallRating": 85,
"companyFitRating": "HIGH",
"strongPoints": ["Strong technical skills"],
"weakPoints": ["Limited leadership experience"]
},
"specific": null
}
}
],
"total": 5,
"page": 1,
"limit": 20,
"totalPages": 1
}
```
Both id spellings are always present and always identical, so you can move field by field at your own pace.
Rows produced by a [custom agent](/api-reference/agents/create-agent#custom-agents) carry an [`analytics`](/api-reference/conversations/get-conversation#custom-agent-analytics) object instead — the same shape returned by `GET /conversations/{id}`, so a page needs no follow-up request per row to read its results. Such rows typically have **no** `analysis`, since the recruiting jobs do not run for them.
## Tracking Progress
```javascript theme={null}
async function trackConversations(contactId) {
const response = await fetch(
`https://api.instaview.sk/conversations?contactId=${contactId}`,
{
headers: { Authorization: `Bearer ${apiKey}` },
// Without a deadline a stalled request never settles.
signal: AbortSignal.timeout(10_000),
},
);
if (!response.ok) {
throw new Error(
`Listing conversations failed: ${response.status} ${response.statusText}`,
);
}
const { data, total } = await response.json();
return {
total,
completed: data.filter((c) => c.status === "COMPLETED").length,
inProgress: data.filter((c) => c.status === "IN_PROGRESS").length,
scheduled: data.filter((c) => c.status === "SCHEDULED").length,
};
}
```
## Company Isolation
Every conversation returned belongs to a contact in your API key's company. Conversations from another company are never listed.
## Related Resources
Learn how conversations are run and analysed
Retrieve a single conversation by ID
Understand pagination best practices
Manage the people you call
## OpenAPI
````yaml GET /conversations
openapi: 3.0.0
info:
title: InstaView API
description: |-
InstaView API Documentation
## Authentication
All endpoints require API key authentication using Bearer token:
```
Authorization: Bearer sk_your_api_key_here
```
## API Key Management
The API Key module provides comprehensive key management for:
- **Direct Client Keys**: Company-scoped keys for your applications
- **ATS Partner Keys**: Resource-scoped keys for ATS integrations
### Key Features
- HMAC-SHA256 hashing for API key storage
- Configurable rate limiting
- Comprehensive audit logging
- Company-level isolation
- Resource scoping for ATS partners
version: 1.0.0
contact: {}
servers:
- url: https://api.instaview.sk
description: Production API Gateway
security: []
tags: []
paths:
/conversations:
get:
tags:
- Conversations
summary: List conversations
description: >-
Lists conversations within the API key's company. Every filter is
optional: pass `contactId` to narrow the page to one contact
(`candidateId` is accepted as its legacy alias), and omit it to list all
of them.
operationId: PublicInterviewsController_listInterviews_v1
parameters:
- name: page
required: false
in: query
description: Page number (1-based)
schema:
minimum: 1
maximum: 10000
default: 1
example: 1
type: integer
- name: limit
required: false
in: query
description: Number of items per page
schema:
minimum: 1
maximum: 100
default: 20
example: 20
type: integer
- name: companyId
required: false
in: query
description: Company ID (required for ATS keys, optional for regular keys)
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
format: uuid
- name: contactId
required: false
in: query
description: Filter by contact ID. Optional; omit it to list every conversation.
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
format: uuid
- name: candidateId
required: false
in: query
description: >-
Deprecated alias of `contactId`. Optional. Sending both is allowed
only when they hold the same value.
schema:
example: 123e4567-e89b-12d3-a456-426614174000
type: string
format: uuid
deprecated: true
- name: agentId
required: false
in: query
description: Filter by agent ID
schema:
example: 987e6543-e21b-12d3-a456-426614174000
type: string
format: uuid
- name: status
required: false
in: query
description: Filter by conversation status
schema:
type: string
enum:
- UNDEFINED
- SCHEDULED
- CANCELLED
- FAILED
- COMPLETED
- IN_PROGRESS
- UNREACHABLE
example: SCHEDULED
- name: jobId
required: false
deprecated: true
in: query
description: '[Deprecated] Filter by the job the conversation is for.'
schema:
example: 456e7890-e12b-34d5-a678-901234567890
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicListInterviewsResponseDto'
security:
- bearer: []
components:
schemas:
PublicListInterviewsResponseDto:
type: object
properties:
data:
description: Array of conversations
type: array
items:
$ref: '#/components/schemas/PublicInterviewDto'
total:
type: number
description: Total number of items
example: 150
page:
type: number
description: Current page number
example: 1
limit:
type: number
description: Number of items per page
example: 20
totalPages:
type: number
description: Total number of pages
example: 8
required:
- data
- total
- page
- limit
- totalPages
PublicInterviewDto:
type: object
properties:
id:
type: string
format: uuid
description: Conversation ID
example: 123e4567-e89b-12d3-a456-426614174000
contactId:
type: string
format: uuid
description: Contact ID
example: 987e6543-e21b-12d3-a456-426614174000
candidateId:
type: string
format: uuid
description: >-
Deprecated alias of `contactId`, always identical to it. Kept for
the life of v1 so existing integrations keep working; new callers
should read `contactId`.
example: 987e6543-e21b-12d3-a456-426614174000
deprecated: true
agentId:
type: string
description: Agent ID
format: uuid
example: 456e7890-e12b-34d5-a678-901234567890
jobId:
type: string
description: Job ID associated with this conversation, if any
format: uuid
nullable: true
example: 123e4567-e89b-12d3-a456-426614174000
runId:
type: string
description: >-
The run that produced this conversation, or `null` for one created
on its own. A run mints one conversation per contact, so this is how
a conversation is traced back to the batch it came from without
listing the run.
format: uuid
nullable: true
example: 789e0123-e45b-67d8-a901-234567890123
status:
type: string
description: Conversation status
enum:
- UNDEFINED
- SCHEDULED
- CANCELLED
- FAILED
- COMPLETED
- IN_PROGRESS
- UNREACHABLE
example: SCHEDULED
scheduledAt:
type: string
format: date-time
description: Scheduled time
example: '2025-11-20T10:00:00Z'
durationMinutes:
type: number
description: Conversation duration in minutes
example: 15
finishedDate:
type: string
format: date-time
description: Finished date
example: '2025-11-20T10:15:00Z'
metadata:
type: object
description: Custom metadata
example:
externalInterviewId: INT-789
callAttempts:
description: >-
Call attempt logs for this conversation. Present for PHONE
conversations, typically empty or undefined for ONLINE ones.
type: array
items:
$ref: '#/components/schemas/PublicCallAttemptDto'
analysis:
description: >-
Conversation analysis data. Present only if analysis has been
generated.
allOf:
- $ref: '#/components/schemas/PublicConversationAnalysisDto'
analytics:
allOf:
- $ref: '#/components/schemas/ConversationAnalytics'
description: >-
What the agent's own analytics configuration produced on this call:
extracted fields, match score, outcomes and tags. Present only for a
custom agent whose after-call analysis has run.
createdAt:
type: string
description: Created timestamp
example: '2024-11-16T10:30:00Z'
updatedAt:
type: string
description: Updated timestamp
example: '2024-11-16T10:30:00Z'
isTest:
type: boolean
description: >-
Whether this is a test conversation. A test conversation is created
with isTest=true, completes immediately without consuming billing
minutes, and is excluded from billing and usage summaries. Use them
to exercise webhook handlers and integration flows.
example: false
required:
- id
- contactId
- candidateId
- agentId
- status
- scheduledAt
- createdAt
- updatedAt
PublicCallAttemptDto:
type: object
properties:
id:
type: string
description: Call attempt ID
example: c9c9a6e8-fb4a-45f3-80fc-bf94f071cd2a
direction:
type: string
description: Call direction (inbound / outbound)
enum:
- UNDEFINED
- INBOUND
- OUTBOUND
example: OUTBOUND
status:
type: string
description: Current status of the call attempt
enum:
- UNDEFINED
- SCHEDULED
- IN_PROGRESS
- COMPLETED
- NO_ANSWER
- BUSY
- FAILED
- CANCELLED
- VOICEMAIL
- REJECTED
- NO_CONSENT
- TIMEOUT
- MAX_ATTEMPTS_REACHED
- HUMAN_CONTACT_REQUESTED
- OTHER_ROLE_INTEREST
- POLITE_DECLINE
- TIMING_ISSUE
example: COMPLETED
reasonCode:
type: string
description: Machine-readable reason code for failures or special outcomes
example: NO_ANSWER
notes:
type: string
description: Human-readable notes associated with this call attempt
example: Candidate did not pick up, mailbox full
retryNumber:
type: number
description: >-
Retry number for this attempt (starting from 0 or 1 depending on
implementation)
example: 2
recordingUrl:
type: string
description: URL to the call recording, if available
example: https://audio.example.com/recording.mp3
duration:
type: number
description: Duration of the call attempt in seconds
example: 180
scheduledAt:
type: string
format: date-time
description: Scheduled time for this call attempt (ISO 8601, UTC)
example: '2025-07-22T10:00:00Z'
calledAt:
type: string
format: date-time
description: Actual time when the call started (ISO 8601, UTC)
example: '2025-07-22T10:01:00Z'
transcript:
description: >-
Transcript segments for this call attempt, ordered chronologically.
Each segment contains the speaker, text content, and timing. Omitted
when the conversation has no transcript or the call attempt did not
produce one.
type: array
items:
$ref: '#/components/schemas/PublicTranscriptSegmentDto'
required:
- id
- direction
PublicConversationAnalysisDto:
type: object
properties:
id:
type: string
description: Analysis ID
example: 123e4567-e89b-12d3-a456-426614174000
general:
description: General analysis data
allOf:
- $ref: '#/components/schemas/PublicGeneralAnalysisDto'
specific:
type: object
description: >-
Specific analysis data, depending on the agent's focus (e.g.
language test scores, outreach feedback)
example:
pronunciationScores:
accuracy: 90
fluency: 85
prosody: 82
grammar:
level: C1
required:
- id
- general
ConversationAnalytics:
type: object
description: >-
What the agent's own `analyticsConfig` produced on this call. Present
only for a custom agent whose after-call analysis has run. Distinct from
`analysis`, which is the recruiting pipeline's output.
Each slice is written by its own after-call job and each job self-gates
on the agent's config, so an absent field means “not configured, or not
run yet”.
required:
- matchScore
- updatedAt
properties:
matchScore:
type: number
description: The weighted overall match score. Null until scoring has run.
nullable: true
minimum: 0
maximum: 100
example: 72
fields:
type: array
description: The agent's extraction targets, resolved against this call.
items:
$ref: '#/components/schemas/AnalyticsFieldResult'
scoring:
allOf:
- $ref: '#/components/schemas/AnalyticsScoring'
description: How the match score was made up.
outcomes:
type: array
description: The agent's outcomes, decided for this call.
items:
$ref: '#/components/schemas/AnalyticsOutcomeResult'
tags:
type: array
description: The agent's output tags, assigned or not.
items:
$ref: '#/components/schemas/AnalyticsTagResult'
qa:
type: array
description: The flow's looping questions, answered from the transcript.
items:
$ref: '#/components/schemas/AnalyticsQaEntry'
evaluation:
allOf:
- $ref: '#/components/schemas/AnalyticsEvaluation'
description: Purpose-driven evaluation of the call.
sentiment:
allOf:
- $ref: '#/components/schemas/AnalyticsSentiment'
description: Overall tone of the call.
summary:
type: string
description: Generic call summary.
example: Qualified lead; demo booked for Thursday.
updatedAt:
type: string
format: date-time
description: When these analytics were last written (UTC).
example: '2026-08-03T10:30:00Z'
PublicTranscriptSegmentDto:
type: object
description: >-
A single segment of a call attempt transcript: one utterance, by either
the agent or the contact.
properties:
speaker:
type: string
description: Who spoke this segment
enum:
- AI
- HUMAN
example: AI
text:
type: string
description: Transcribed text of the utterance
example: Hello, thank you for taking the time to speak with me today.
startTime:
type: number
description: Start time of the segment in seconds from the start of the recording
example: 0
minimum: 0
endTime:
type: number
description: End time of the segment in seconds from the start of the recording
example: 3.5
minimum: 0
language:
type: string
description: BCP-47 language code detected for this segment (e.g. 'en', 'sk')
example: en
pattern: ^[A-Za-z]{2,3}(-[A-Za-z0-9]{2,8})*$
required:
- speaker
- text
- startTime
- endTime
PublicGeneralAnalysisDto:
type: object
properties:
overallRating:
type: number
nullable: true
description: >-
Overall rating (0-100). Null when scoring did not complete — see
scoringIncompleteReason. A null rating is never a low one: it means
no score was produced, not that the candidate scored badly.
example: 85
scoringIncompleteReason:
type: string
description: >-
Why no overall rating was produced. Absent on a complete analysis.
'model_unavailable' means the scoring model could not be reached and
the analysis is queued to be re-run; 'model_error' means it answered
unusably and the analysis will not be retried on its own.
enum:
- model_unavailable
- model_error
example: model_unavailable
companyFitRating:
type: string
description: Company fit rating
enum:
- UNDEFINED
- LOW
- MEDIUM
- HIGH
example: HIGH
education:
type: string
description: Summary of education analysis
example: Master's degree in Computer Science
experience:
type: string
description: Summary of experience analysis
example: 5 years of experience in software development
strongPoints:
description: Strong points and advantages found in the call
example:
- Excellent communication skills
- Strong technical expertise in React and Node.js
- Proven track record of leading teams
type: array
items:
type: string
weakPoints:
description: Weak points, or areas for improvement, found in the call
example:
- Limited experience with microservices
- Needs improvement in system design
type: array
items:
type: string
evaluation:
description: Overall evaluation summary and recommendations
example:
- Strong candidate with relevant experience
- Good cultural fit for the team
- Recommended for next round
type: array
items:
type: string
status:
type: number
description: Analysis processing status
enum:
- 1
- 2
- 3
- 4
example: 3
createdAt:
type: string
description: Created timestamp (UTC)
example: '2024-11-16T10:30:00Z'
format: date-time
updatedAt:
type: string
description: Updated timestamp (UTC)
example: '2024-11-16T10:30:00Z'
format: date-time
required:
- createdAt
- updatedAt
AnalyticsFieldResult:
type: object
description: One extraction target, resolved against the call.
required:
- key
- label
- type
- value
properties:
key:
type: string
description: The key configured on the agent.
example: budget_confirmed
label:
type: string
example: Budget confirmed
type:
type: string
enum:
- string
- number
- bool
- enum
value:
description: >-
The extracted value, coerced to `type`. `null` when the call did not
surface it — which is distinct from a `false` or empty value that
WAS surfaced.
anyOf:
- type: string
nullable: true
- type: number
nullable: true
- type: boolean
nullable: true
example: true
confidence:
type: number
minimum: 0
maximum: 1
description: Model confidence, 0..1.
evidence:
type: string
description: Short transcript-grounded justification.
example: Said they have signed off on 15k for this quarter
AnalyticsScoring:
type: object
description: The overall match score and what made it up.
required:
- total
- items
properties:
total:
type: number
minimum: 0
maximum: 100
description: The weighted overall match score.
example: 72
items:
type: array
description: One entry per scored item.
items:
$ref: '#/components/schemas/AnalyticsScoreItem'
AnalyticsOutcomeResult:
type: object
description: One of the agent's outcomes, decided for this call.
required:
- key
- label
- met
properties:
key:
type: string
description: The key configured on the agent.
example: meeting_booked
label:
type: string
example: Meeting booked
met:
type: boolean
description: Whether the call achieved it.
example: true
confidence:
type: number
minimum: 0
maximum: 1
evidence:
type: string
description: Short transcript-grounded justification.
AnalyticsTagResult:
type: object
description: One of the agent's output tags, assigned or not.
required:
- key
- label
- applied
properties:
key:
type: string
description: The key configured on the agent.
example: needs_followup
label:
type: string
example: Needs follow-up
applied:
type: boolean
description: Whether the AI applied it to this call.
example: true
reason:
type: string
description: Why.
AnalyticsQaEntry:
type: object
description: One of the flow's looping questions, answered from the transcript.
required:
- id
- question
- answered
- answer
properties:
id:
type: string
format: uuid
description: >-
Id of the flow's looping question — the same id the agent read
returns.
question:
type: string
description: The question, as designed.
answered:
type: boolean
description: >-
Whether the call actually covered it. Distinguishes “not discussed”
from an empty answer.
example: true
answer:
type: string
description: The answer as given on the call; empty when not answered.
evidence:
type: string
description: Short transcript-grounded justification.
AnalyticsEvaluation:
type: object
description: >-
Purpose-driven evaluation of the call, driven by the agent's design
rather than a job spec.
required:
- strengths
- concerns
- objections
- assessment
properties:
strengths:
type: array
description: What went well.
items:
type: string
concerns:
type: array
description: What went poorly, and the risks.
items:
type: string
objections:
type: array
description: Objections or hesitations the contact raised.
items:
type: string
assessment:
type: array
description: Overall assessment, a few holistic lines.
items:
type: string
AnalyticsSentiment:
type: object
description: Overall tone of the call and how it moved.
required:
- overall
properties:
overall:
type: string
enum:
- positive
- neutral
- negative
example: positive
score:
type: number
minimum: 0
maximum: 1
description: 0 (very negative) .. 1 (very positive).
trajectory:
type: string
enum:
- improving
- declining
- steady
- mixed
notes:
type: string
description: One-line note explaining the read.
AnalyticsScoreItem:
type: object
description: One item contributing to the match score.
required:
- key
- kind
- label
- score
properties:
key:
type: string
description: >-
The extraction target's or criterion's key, or the flow question's
id.
example: budget_confirmed
kind:
type: string
description: What kind of thing was scored.
enum:
- field
- question
- criterion
example: field
label:
type: string
description: The field/criterion label, or the question itself.
example: Budget confirmed
score:
type: number
minimum: 0
maximum: 100
description: How well this item scored.
example: 80
weightPercent:
type: number
description: >-
Share of the overall match score this item accounts for, in percent.
Computed from the configured weights (which are relative, not a
budget), so the shares across all items sum to 100.
minimum: 0
maximum: 100
example: 33.3
importance:
type: string
enum:
- REQUIRED
- PREFERRED
reasoning:
type: string
description: Why it scored that way.
securitySchemes:
bearer:
type: http
scheme: bearer
description: API key for authentication using Bearer scheme
````