> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userjourneys.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Interviews

> List and retrieve individual interviews — access transcripts, summaries, and structured question answers.

An interview is a single conversation between an AI interviewer and a respondent. Each interview belongs to a [study](/api/studies).

***

## `GET /v1/interviews`

List interviews for a study. Filter by status, reference ID, or quality score.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. See [Authentication](/api/authentication).
</ParamField>

<ParamField query="study_id" type="string" required>
  Study ID (UUID). Only interviews belonging to this study are returned.
</ParamField>

<ParamField query="status" type="string">
  Filter by status. Common values: `"completed"`, `"started"`.
</ParamField>

<ParamField query="reference_id" type="string">
  Filter by the reference ID you passed via `?reference_id=` on the interview link. Use this to find a specific user's interview.
</ParamField>

<ParamField query="quality_score" type="string">
  Filter by quality: `"insightful"`, `"successful"`, or `"unsuccessful"`.
</ParamField>

<ParamField query="limit" type="integer">
  Number of interviews to return. Default `20`, max `100`.
</ParamField>

<ParamField query="starting_after" type="string">
  Cursor for pagination. Pass the `id` of the last interview from the previous page.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl "https://app.userjourneys.ai/api/v1/interviews?study_id=e5f6a7b8-1234-56cd-ef78-222222222222" \
    -H "Authorization: Bearer uj_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const studyId = "e5f6a7b8-1234-56cd-ef78-222222222222";
  const response = await fetch(
    `https://app.userjourneys.ai/api/v1/interviews?study_id=${studyId}`,
    {
      headers: {
        Authorization: "Bearer uj_live_your_key_here",
      },
    }
  );
  const { data, has_more } = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.userjourneys.ai/api/v1/interviews",
      headers={"Authorization": "Bearer uj_live_your_key_here"},
      params={"study_id": "e5f6a7b8-1234-56cd-ef78-222222222222"},
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "object": "list",
    "data": [
      {
        "id": "a1b2c3d4-5678-90ab-cdef-111111111111",
        "object": "interview",
        "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
        "status": "completed",
        "reference_id": "user_12345",
        "respondent_email": null,
        "language": "en",
        "quality_score": "insightful",
        "duration_secs": 580,
        "headline": "User loves the onboarding but struggles with payment",
        "summary": "The respondent had a positive first impression of the product...",
        "started_at": "2026-03-11T14:20:00.000Z",
        "completed_at": "2026-03-11T14:30:00.456Z",
        "created_at": "2026-03-11T14:20:00.000Z"
      }
    ],
    "has_more": false
  }
  ```
</ResponseExample>

<Tip>
  Filter by `reference_id` to find a specific user's interview: `?study_id=...&reference_id=user_12345`
</Tip>

***

## `GET /v1/interviews/:id`

Retrieve a single interview with the full transcript and structured question answers.

### Request

<ParamField header="Authorization" type="string" required>
  Bearer token. See [Authentication](/api/authentication).
</ParamField>

<ParamField path="id" type="string" required>
  Interview ID (UUID). This is the `interview_id` from the [webhook payload](/api/webhooks#event-interviewcompleted).
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://app.userjourneys.ai/api/v1/interviews/a1b2c3d4-5678-90ab-cdef-111111111111 \
    -H "Authorization: Bearer uj_live_your_key_here"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch(
    "https://app.userjourneys.ai/api/v1/interviews/a1b2c3d4-5678-90ab-cdef-111111111111",
    {
      headers: {
        Authorization: "Bearer uj_live_your_key_here",
      },
    }
  );
  const interview = await response.json();
  // interview.transcript — full conversation
  // interview.question_answers — structured per-question data
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      "https://app.userjourneys.ai/api/v1/interviews/a1b2c3d4-5678-90ab-cdef-111111111111",
      headers={"Authorization": "Bearer uj_live_your_key_here"},
  )
  interview = response.json()
  # interview["transcript"] — full conversation
  # interview["question_answers"] — structured per-question data
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "id": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "object": "interview",
    "study_id": "e5f6a7b8-1234-56cd-ef78-222222222222",
    "status": "completed",
    "reference_id": "user_12345",
    "respondent_email": null,
    "language": "es",
    "quality_score": "insightful",
    "duration_secs": 580,
    "headline": "User loves the onboarding but struggles with payment",
    "summary": "The respondent had a positive first impression of the product...",
    "started_at": "2026-03-11T14:20:00.000Z",
    "completed_at": "2026-03-11T14:30:00.456Z",
    "created_at": "2026-03-11T14:20:00.000Z",
    "transcript": [
      {
        "role": "agent",
        "message": "Gracias por unirte hoy. Cuéntame sobre tu experiencia.",
        "translated": "Thanks for joining today. Tell me about your experience.",
        "time_in_call_secs": 0
      },
      {
        "role": "user",
        "message": "El proceso fue bastante sencillo al principio...",
        "translated": "The process was pretty straightforward at first...",
        "time_in_call_secs": 4
      }
    ],
    "question_answers": [
      {
        "question_index": 0,
        "question_text": "What was your first impression of the product?",
        "answer_summary": "Found it intuitive but hit a snag at the payment step",
        "answer_excerpt": [
          { "role": "user", "message": "It was pretty smooth until..." }
        ]
      }
    ]
  }
  ```
</ResponseExample>

Returns `404` if the interview doesn't exist or doesn't belong to your project.

***

## Interview object

<ResponseField name="id" type="string">
  Interview ID (UUID).
</ResponseField>

<ResponseField name="object" type="string">
  `"interview"`
</ResponseField>

<ResponseField name="study_id" type="string">
  The study this interview belongs to.
</ResponseField>

<ResponseField name="status" type="string">
  `"completed"`, `"started"`, or `"processing"`.
</ResponseField>

<ResponseField name="reference_id" type="string | null">
  Custom identifier passed via `?reference_id=` on the interview link.
</ResponseField>

<ResponseField name="respondent_email" type="string | null">
  Email entered during or after the interview. `null` if not collected.
</ResponseField>

<ResponseField name="language" type="string | null">
  Detected language code (e.g. `"en"`, `"es"`, `"de"`).
</ResponseField>

<ResponseField name="quality_score" type="string | null">
  `"insightful"`, `"successful"`, or `"unsuccessful"`.
</ResponseField>

<ResponseField name="duration_secs" type="integer | null">
  Interview length in seconds.
</ResponseField>

<ResponseField name="headline" type="string | null">
  AI-generated one-line summary.
</ResponseField>

<ResponseField name="summary" type="string | null">
  AI-generated paragraph summary.
</ResponseField>

<ResponseField name="started_at" type="string">
  Interview start time (ISO 8601).
</ResponseField>

<ResponseField name="completed_at" type="string | null">
  Interview end time (ISO 8601).
</ResponseField>

<ResponseField name="created_at" type="string">
  Record creation time (ISO 8601).
</ResponseField>

### Detail-only fields

These fields are only included in `GET /v1/interviews/:id` responses:

<ResponseField name="transcript" type="object[]">
  Full conversation transcript, ordered chronologically.

  <Expandable title="properties">
    <ResponseField name="role" type="string">
      `"agent"` or `"user"`.
    </ResponseField>

    <ResponseField name="message" type="string">
      The message text in the original language.
    </ResponseField>

    <ResponseField name="translated" type="string">
      English translation. Only present for non-English interviews.
    </ResponseField>

    <ResponseField name="time_in_call_secs" type="number">
      Seconds into the interview when this message occurred.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="question_answers" type="object[]">
  Structured answers extracted from the transcript, one per interview question.

  <Expandable title="properties">
    <ResponseField name="question_index" type="integer">
      Question position (0-indexed).
    </ResponseField>

    <ResponseField name="question_text" type="string">
      The question that was asked.
    </ResponseField>

    <ResponseField name="answer_summary" type="string | null">
      AI-generated summary of the respondent's answer.
    </ResponseField>

    <ResponseField name="answer_excerpt" type="object[]">
      Relevant transcript excerpt.
    </ResponseField>
  </Expandable>
</ResponseField>