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
Uselist_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.