> ## 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.
# Get Conversation
> Returns a single conversation, ensuring it belongs to the API key's company.
`GET /interviews/{id}` 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).
Retrieves a single conversation by ID, including full details, transcript, analysis or analytics, and call attempt information.
## Overview
This endpoint returns everything recorded about one conversation: its current status, the transcript, the AI analysis or analytics when there is any, and every associated field. It is the primary way to read a call's results.
## Use Cases
* **Read results**: analysis, analytics and transcript once the call has finished
* **Check status**: follow a conversation's progress
* **Access transcripts**: the full transcript of what was said
* **Review scoring**: the AI-generated assessment and its scores
## Response Data
The response includes:
* **Conversation details**: status, timestamps, duration, scheduled time
* **Transcript**: the full transcript, when available
* **Analysis**: AI-generated assessment with scores and recommendations
* **Call attempts**: each attempt and its recording
* **Contact & agent**: `contactId` (with `candidateId` alongside it, always identical) and `agentId`
* **Run**: `runId`, the [run](/guides/resources/runs) that produced this conversation, or `null` for one created on its own
## Analysis Data
Once a conversation has completed, the response carries its analysis. The structure is a `general` object holding the overall assessment, plus an optional `specific` object for data particular to the conversation type:
```json theme={null}
{
"analysis": {
"id": "550e8400-e29b-41d4-a716-446655440000",
"general": {
"overallRating": 85,
"companyFitRating": "HIGH",
"education": "MASTER_LEVEL",
"experience": "THREE_TO_5_YEARS",
"strongPoints": ["Strong technical skills", "Clear communication"],
"weakPoints": ["Limited leadership experience"],
"evaluation": ["Strong hire for senior individual contributor role"],
"status": 3,
"createdAt": "2024-01-20T14:30:00Z",
"updatedAt": "2024-01-20T14:30:00Z"
},
"specific": null
}
}
```
The `specific` field carries data particular to the conversation type, when there is any. See the [Conversations Resource Guide](/guides/resources/conversations#conversation-types--analysis) for what each type produces.
Analysis is only available once the conversation has completed. While one is scheduled or
in progress, `analysis` is `null`.
## Custom Agent Analytics
A conversation run by a [custom agent](/api-reference/agents/create-agent#custom-agents) carries a second, separate object: `analytics`, containing whatever that agent's `analyticsConfig` asked for. It is **not** a variant of `analysis` — `analysis` is the recruiting pipeline's output and is typically absent on a custom call, while `analytics` is the agent's own design.
```json theme={null}
{
"analytics": {
"matchScore": 72,
"fields": [
{
"key": "budget_confirmed",
"label": "Budget confirmed",
"type": "bool",
"value": true,
"confidence": 0.9,
"evidence": "Said they have signed off on 15k for this quarter"
},
{ "key": "timeline", "label": "Timeline", "type": "string", "value": null }
],
"scoring": {
"total": 72,
"items": [
{
"key": "budget_confirmed",
"kind": "field",
"label": "Budget confirmed",
"score": 90,
"weightPercent": 50,
"importance": "REQUIRED"
}
]
},
"outcomes": [{ "key": "meeting_booked", "label": "Meeting booked", "met": true }],
"tags": [{ "key": "needs_followup", "label": "Needs follow-up", "applied": false }],
"qa": [
{
"id": "3f1a8c2e-question-uuid",
"question": "What are you using today?",
"answered": true,
"answer": "Spreadsheets, rebuilt by hand every week",
"evidence": "It's the worst two hours of my Monday"
}
],
"evaluation": {
"strengths": ["Clear pain point, already shopping for a replacement"],
"concerns": ["Finance sign-off not secured"],
"objections": ["Worried about migrating two years of historical data"],
"assessment": ["Strong fit; the only real risk is procurement timing"]
},
"sentiment": { "overall": "positive", "score": 0.8, "trajectory": "improving" },
"summary": "Qualified lead; demo booked for Thursday.",
"updatedAt": "2026-08-03T14:30:00Z"
}
}
```
The `key` on each field, outcome and tag is the one configured on the agent, so you can switch on it directly. Reading it back:
* `value: null` on a field means the call did not surface it — distinct from a `false` or empty value that **was** surfaced.
* In `scoring.items`, an entry with `kind: "question"` carries the flow question's **id** rather than a configured key — a question has none, which is why its scoring is set inline on the question. Entries with `kind: "field"` or `"criterion"` carry the configured key.
* `weightPercent` is each scored item's share of the match score, so the shares sum to exactly 100. The weights you configured are relative, not percentages.
* `matchScore` is always present, and `null` when scoring has not run yet.
* In `qa`, `answered: false` means the call never reached the question, not that it was answered with nothing — `answer` is empty in both cases, so switch on `answered`.
* `evaluation` holds four independent arrays of lines (`strengths`, `concerns`, `objections`, `assessment`); any one can be empty while the others are populated.
* Each slice is produced by its own after-call job, and each job only runs when the agent asked for it — so an absent `outcomes` or `sentiment` means "not configured, or not run yet".
The same object is pushed to your `analysis.completed` [webhook](/guides/webhooks), so you
do not have to poll for it.
## Status Checking
```javascript theme={null}
async function checkConversationStatus(conversationId) {
const response = await fetch(
`https://api.instaview.sk/conversations/${conversationId}`,
{
headers: { Authorization: `Bearer ${apiKey}` },
// Without a deadline a stalled request never settles.
signal: AbortSignal.timeout(10_000),
},
);
if (!response.ok) {
throw new Error(
`Reading the conversation failed: ${response.status} ${response.statusText}`,
);
}
const data = await response.json();
return {
status: data.status,
hasAnalysis: data.analysis !== null,
durationMinutes: data.durationMinutes,
finishedDate: data.finishedDate,
};
}
```
## Company Isolation
You can only read conversations belonging to contacts in your own company. Reaching for one from another company returns `403 Forbidden`.
## Error Scenarios
* **404 Not Found**: the conversation does not exist, or has been deleted
* **403 Forbidden**: the conversation belongs to a different company
## Related Resources
Learn how conversations are run and analysed
List every conversation for one contact
Schedule a new call
Download the analysis PDF report
## OpenAPI
````yaml GET /conversations/{id}
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/{id}:
get:
tags:
- Conversations
summary: Get conversation by ID
description: >-
Returns a single conversation, ensuring it belongs to the API key's
company.
operationId: PublicInterviewsController_getInterviewById_v1
parameters:
- name: id
required: true
in: path
schema:
type: string
format: uuid
- name: companyId
required: false
in: query
description: >-
Required for ATS API keys to specify which company to access.
Ignored for standard company API keys.
schema:
type: string
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/PublicInterviewDto'
security:
- bearer: []
components:
schemas:
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
````