Completing Interviews via API
Finalize interviews with POST /interviews/{id}/complete, then poll the read endpoint for the asynchronous AI analysis.
Completing an interview does two things: it marks the session finished, and it kicks off AI analysis in the background. Call it when the AI signals the interview is done, or when the respondent ends the conversation themselves. Then read the results, including the analysis and your own respondent ID, from the read endpoint.
The endpoint
POST https://www.koji.so/api/v1/interviews/{interview_id}/complete
Marks the interview as completed and triggers AI analysis in the background.
Headers
| Header | Value | Required |
|---|---|---|
Authorization | Bearer pk_live_... | Yes: Your project API key |
X-Session-Token | <session_token from start> | Yes: The session token returned by the start endpoint. Proves the request belongs to this respondent session |
Content-Type | application/json | Yes: JSON request body |
Like the message endpoint, complete requires both the API key (with interview:complete permission) and the respondent's session token. The study owner also needs the Interviews or Enterprise plan: the headless API isn't included on Free or Insights.
Request body
{
"reason": "natural"
}
reasonis optional (default'natural'). Use it to record why the interview ended, e.g.'natural','user_ended','timeout'.
Response
{
"status": "completed",
"interview_id": "9f4c1e2a-7b3d-4e8f-a1c5-2d6b8e0f4a7c",
"completed_at": "2026-07-14T12:34:56.000Z",
"stats": {
"message_count": 18,
"user_messages": 9,
"duration_seconds": 432
},
"analysis": null,
"analysis_pending": true
}
The stats block summarizes the session:
message_count: total messages in the transcript.user_messages: how many came from the respondent.duration_seconds: time from start to completion.
Analysis runs asynchronously. In practice analysis is null and analysis_pending is true in this response. Poll the read endpoint to retrieve it.
Analysis is asynchronous
The AI analysis runs in the background after completion, so the completion response almost never carries it. (If an analysis already exists for the interview, it is returned and analysis_pending is false.) To retrieve it, poll GET /interviews/{id} until analysis is non-null:
// Mark the interview complete
await fetch(`https://www.koji.so/api/v1/interviews/${interviewId}/complete`, {
method: 'POST',
headers: {
'Authorization': 'Bearer pk_live_wJalrXUtnFEMI4K7MDENGbPxRfiCYz2K',
'X-Session-Token': sessionToken,
'Content-Type': 'application/json',
},
body: JSON.stringify({ reason: 'natural' }),
})
// Analysis runs in the background: poll the read endpoint until it lands
async function waitForAnalysis(interviewId) {
for (let attempt = 0; attempt < 20; attempt++) {
const res = await fetch(`https://www.koji.so/api/v1/interviews/${interviewId}`, {
headers: { 'Authorization': 'Bearer pk_live_wJalrXUtnFEMI4K7MDENGbPxRfiCYz2K' },
})
const data = await res.json()
if (data.analysis) return data.analysis
await new Promise(r => setTimeout(r, 15000))
}
return null
}
The read endpoint requires the interview:read permission and no session token, which makes it a natural fit for a server-side worker. See API Key Permissions.
Reading the finished interview
GET https://www.koji.so/api/v1/interviews/{interview_id}
The read endpoint returns everything about one interview:
{
"interview_id": "9f4c1e2a-7b3d-4e8f-a1c5-2d6b8e0f4a7c",
"status": "completed",
"created_at": "2026-07-14T12:27:44.000Z",
"updated_at": "2026-07-14T12:34:56.000Z",
"respondent": {
"id": "c3a9e1f0-5d2b-4c7a-9e8f-1b6d4a2c0e93",
"external_id": "user_4821",
"display_name": null,
"started_at": "2026-07-14T12:27:44.000Z",
"completed_at": "2026-07-14T12:34:56.000Z"
},
"stats": {
"message_count": 18,
"user_messages": 9,
"assistant_messages": 9,
"duration_seconds": 432
},
"transcript": [
{ "id": "...", "role": "assistant", "content": "...", "timestamp": "..." }
],
"analysis": { "...": "..." }
}
respondent.external_idis the ID you passed in the start request. Use it to join the results back to the user, account or deal in your own system.statusisactivewhile the conversation is open, thencompleted,partialorabandoned.analysisis returned for all three finished statuses, not onlycompleted. An interview the study owner marked as done (partial) and a drop-off (abandoned) are analysed too, so your worker should treat any finished status as "ready onceanalysisis present".- Preview interviews (tests you ran yourself before launch) are not responses. The read endpoint returns 404 for them.
Read responses also carry X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers, so a polling worker can pace itself.
Try it with curl
curl -X POST https://www.koji.so/api/v1/interviews/9f4c1e2a-7b3d-4e8f-a1c5-2d6b8e0f4a7c/complete \
-H "Authorization: Bearer pk_live_wJalrXUtnFEMI4K7MDENGbPxRfiCYz2K" \
-H "X-Session-Token: 5b1f0c7d-9e42-4a68-b3c1-d7f28a904e5b" \
-H "Content-Type: application/json" \
-d '{ "reason": "natural" }'
Then fetch the results once analysis has had time to run:
curl https://www.koji.so/api/v1/interviews/9f4c1e2a-7b3d-4e8f-a1c5-2d6b8e0f4a7c \
-H "Authorization: Bearer pk_live_wJalrXUtnFEMI4K7MDENGbPxRfiCYz2K"
analysisis populated only after the interview has finished (completed, partial or abandoned) and the background analysis has run; otherwisenull.stats.duration_secondsisnulluntil the respondent has both started and completed timestamps.
When to call complete
- The
doneframe from the message endpoint hasinterview_complete: true. This is the AI-driven natural ending. See Sending Messages via API. - The respondent ends the conversation early. Record it with
"reason": "user_ended". - Your client times the session out. Record it with
"reason": "timeout".
The reason value is free-form and defaults to 'natural'.
Errors
| Status | error | When | Extra fields |
|---|---|---|---|
| 401 | Missing or invalid authorization header | No Authorization: Bearer header sent | : |
| 401 | Invalid API key | The key does not exist, is malformed, is inactive, or has expired | : |
| 403 | API key does not have interview:complete permission | The key was created without the interview:complete scope | : |
| 403 | Origin not allowed | The browser's Origin header does not match the key's allowed origins | : |
| 403 | Headless API access requires an Interviews plan or higher. | The study owner's plan doesn't include API access. The headless API, API keys and the MCP connector are included on the Interviews and Enterprise plans only | : |
| 401 | Missing X-Session-Token header | The session token header was not sent | : |
| 429 | Rate limit exceeded | The key exceeded its per-minute request limit | retry_after |
| 404 | Interview not found | Unknown interview id (or the interview was deleted) | : |
| 403 | Interview does not belong to this project | The interview belongs to a different study than the API key | : |
| 401 | Invalid session token | The token does not match this interview's respondent | : |
| 500 | Internal server error | Unexpected server failure. Safe to retry with backoff | : |
FAQ
How do I get the analysis?
Poll GET /interviews/{id} after completing. analysis stays null until the background job finishes, then the full analysis object appears in the read response.
What does analysis_pending mean?
It signals that analysis was triggered and has not landed yet. In the completion response it is true unless the interview already had an analysis, because the analysis job starts asynchronously at completion time.
Which permission does polling need?
The read endpoint requires interview:read on the API key. The session token is not needed for reads.
How do I match results to my own users?
Pass your own ID as respondent.external_id in the start request. The read endpoint returns it as respondent.external_id, next to the transcript and analysis.
What if I never call complete?
The interview stays open, so a respondent who comes back can carry on. After a day with no activity, Koji closes it as partial or abandoned and analyses it, and the read endpoint returns that analysis. Calling complete is still the better path: it records your reason, marks the interview completed and starts the analysis straight away.
Related Articles
Sending Messages via API
Send respondent messages to POST /interviews/{id}/message and parse the Server-Sent Events reply stream frame by frame.
Understanding Quality Scores
Learn how Koji scores interview quality from 1 to 5, how to read the Quality Evaluation card, and why only Fair and above (3+) use credits or enter your report.
User Research API: Embed AI Interviews into Any Product or Workflow
How to use Koji's User Research API to run AI-moderated interviews from your own backend. Covers REST endpoints, the embed widget, signed completion webhooks, authentication, rate limits, and headless interview patterns.
Webhook Setup
Set up Koji webhooks: get a signed interview.completed message on your server each time a participant finishes, with your own participant ID and a quality score.
Rate Limits and CORS
Per-key rate limits, X-RateLimit headers, 429 handling with backoff, quota errors, and how CORS works on the Koji API.
Starting Interviews via API
Create interview sessions programmatically with POST /interviews/start: request fields, the 201 response, CRM linking, and voice mode.
API Authentication
How Koji Headless API authentication works: pk_live_ API keys, permissions, session tokens, and origin allowlists.