> ## 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 |

All four tools use the versioned public API; 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.

Use `total_interviews` and each bucket's `interviews`, `audio_interviews`, `video_interviews`, and `chat_interviews` fields. The older count aliases are no longer returned.

## 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 100 spoken transcript segments per request, stopping near 20 KB of transcript text. Start with `message_offset: 0` and follow `next_message_offset` until it is null; `message_limit` accepts 1–100 and defaults to 50. Each segment is at most 1,500 characters and includes its original turn `id`, speaker role, and `text_offset`. When the source has recording timing, segments include `start_s` and `end_s` in seconds from the interview start. Historical untimed messages omit these fields. The response includes `total_message_segments`. System prompts and tool messages are excluded.

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.