Back to docs
API Reference

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

HeaderValueRequired
AuthorizationBearer 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-Typeapplication/jsonYes: 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"
}
  • reason is 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_id is 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.
  • status is active while the conversation is open, then completed, partial or abandoned.
  • analysis is returned for all three finished statuses, not only completed. 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 once analysis is 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"
  • analysis is populated only after the interview has finished (completed, partial or abandoned) and the background analysis has run; otherwise null.
  • stats.duration_seconds is null until the respondent has both started and completed timestamps.

When to call complete

  • The done frame from the message endpoint has interview_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

StatuserrorWhenExtra fields
401Missing or invalid authorization headerNo Authorization: Bearer header sent:
401Invalid API keyThe key does not exist, is malformed, is inactive, or has expired:
403API key does not have interview:complete permissionThe key was created without the interview:complete scope:
403Origin not allowedThe browser's Origin header does not match the key's allowed origins:
403Headless 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:
401Missing X-Session-Token headerThe session token header was not sent:
429Rate limit exceededThe key exceeded its per-minute request limitretry_after
404Interview not foundUnknown interview id (or the interview was deleted):
403Interview does not belong to this projectThe interview belongs to a different study than the API key:
401Invalid session tokenThe token does not match this interview's respondent:
500Internal server errorUnexpected 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.