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

# Interviews

> 4 MCP tools for reading and administering interview records.

Use product terminology in user-facing conversation: an interview is the completed or in-progress research session. Some supplemental responses may retain legacy backend field names.

| Tool                        | Description                                                                        |
| --------------------------- | ---------------------------------------------------------------------------------- |
| `list_interviews`           | List lightweight interviews by study, participant, status, or quality              |
| `get_interview`             | Fetch metadata, a page of spoken messages, recording links, and screener responses |
| `delete_interview`          | Soft-delete an interview owned by the authenticated user                           |
| `get_interview_usage_stats` | Aggregate interview counts and units over a date range                             |

The first three tools use the public API. `get_interview_usage_stats` is supplemental; use `daily`, `weekly`, or `monthly` for its cadence. It reports eligible non-test interview counts and billed units for the selected app, not every interview or interview duration. If `app_id` is omitted, the backend resolves the default app. Missing dates use the 30-day range ending today. The response's `scope` records the applied app, dates, and cadence, including when totals are zero.

## Working with results

Use `list_interviews` for discovery and `get_interview` for evidence. Filter `list_interviews` by `participant_id` to see one participant's interviews; this is the BYOP invitation ID, not a legacy call identifier. You can combine it with `study_id`. Status accepts `pending`, `started`, `live`, `completed`, `ended`, `failed`, or `cancelled`. Quality accepts `Excellent`, `Good`, `Fair`, or `Poor` case-insensitively. Invalid filters return an error. List rows omit transcripts and exclude test or hidden interviews before counting and paging.

`participant_source` is `byop`, `panel`, `external_panel`, `link`, or `unknown`. Anonymous sources have `participant: null`, so fabricated addresses are not presented as contactable people. For BYOP, `participant.id` is the invitation ID, not a unique person ID. `ended_because` uses `completed`, `participant_left`, `time_limit`, `technical_error`, or `screened_out`; it is null when the stored reason cannot be classified.

`get_interview` requires the public `interview_id`. It returns up to eight spoken transcript segments per request. Start with `message_offset: 0` and follow `next_message_offset` until it is null; `message_limit` accepts 1–8. Each segment is at most 1,500 characters and includes its original turn `id`, speaker role, and `text_offset`. The response includes `total_message_segments`. System prompts and tool messages are excluded. Fetch all pages needed for a quotation or analysis; the first page may not contain the relevant passage.

Use `generate_report` and `get_study_report` from the Studies group for cross-interview analysis.

## Deletion

`delete_interview` is destructive and should only be called when the user explicitly asks to delete a specific interview. There is no public `update_interview` or quality-override tool. Do not imply that an agent can hide, relabel, or bulk-delete interviews.