> ## 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 Run Conversations
> Pages through the conversations a run has produced — one per contact it has dispatched, in the same shape `GET /conversations` returns. A run that has not been launched has none yet. Requires `read:runs` and `read:conversations`.
Pages through the conversations one run has produced.
## Overview
A run mints one conversation per contact it dispatches. This endpoint is the per-contact drill-down behind the aggregate on [Get Run](/api-reference/runs/get-run): each row is a full conversation resource, in exactly the shape [List Conversations](/api-reference/conversations/list-conversations) returns — status, call attempts, and the analysis or analytics of the call.
A run that has not been launched has no conversations yet, and answers with an empty page rather than a `404`.
This endpoint needs **both** `read:runs` and `read:conversations`, because its rows are
conversation resources rather than a run-shaped summary. `read:interviews` satisfies the second
— see [Scopes and Permissions](/guides/scopes-and-permissions).
## Use Cases
* **Drill into a batch**: see which contacts were reached and which were not
* **Collect results**: read every analysis or analytics object a run produced, one page at a time
* **Triage**: find the failed and unreachable contacts to follow up by hand
## Basic Usage
```
GET /runs/789e0123-e45b-67d8-a901-234567890123/conversations
```
## With Pagination
```javascript theme={null}
// Walk the whole run, a page at a time
async function* runConversations(runId) {
for (let page = 1; ; page++) {
const response = await fetch(
`https://api.instaview.sk/runs/${runId}/conversations?page=${page}&limit=100`,
{
headers: { Authorization: `Bearer ${apiKey}` },
signal: AbortSignal.timeout(10_000),
},
);
if (!response.ok) {
throw new Error(`Reading the run's conversations failed: ${response.status}`);
}
const body = await response.json();
yield* body.data;
if (page >= body.totalPages) return;
}
}
```
`limit` is capped at 100. See the [Pagination Guide](/guides/pagination) for the page object's fields.
## Reading the Results
Each row is the ordinary conversation resource, so everything the conversation endpoints document applies here:
* `status` is the conversation's own status, not the run's
* `analysis` carries the recruiting pipeline's output, `analytics` whatever a [custom agent's](/api-reference/agents/create-agent#custom-agents) `analyticsConfig` asked for. A custom agent typically produces `analytics` and no `analysis`
* `runId` is this run's id on every row, which is what lets you attribute a conversation to a run when you receive it any other way
Analysis and analytics are only present once a call has completed and its after-call jobs have
run. While the run is dispatching, most rows carry neither.
## Company Isolation
You can only read runs belonging to your own API key's company. A run in another company returns `404 Not Found`, the same as one that does not exist.
## Error Scenarios
* **404 Not Found**: the run does not exist, has been deleted, or belongs to a different company
* **403 Forbidden**: the API key does not hold both `read:runs` and `read:conversations` (`read:interviews` satisfies the second)
## Related Resources
The run's status and aggregate progress
One conversation in full, with its transcript
How a run batches conversations
How pages work across the API
## OpenAPI
````yaml GET /runs/{id}/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:
/runs/{id}/conversations:
get:
tags:
- Runs
summary: List run conversations
description: >-
Pages through the conversations a run has produced — one per contact it
has dispatched, in the same shape `GET /conversations` returns. A run
that has not been launched has none yet. Requires `read:runs` and
`read:conversations`.
operationId: PublicRunsController_listRunConversations_v1
parameters:
- name: id
required: true
in: path
schema:
type: string
format: uuid
- 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: >-
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/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
````