---
title: "List interviews"
method: GET
path: "/api/v1/interviews"
tags: ["Interviews"]
---

# List interviews

`GET /api/v1/interviews`

## Request

- Base URL: `https://app.probbai.com`
- URL: `https://app.probbai.com/api/v1/interviews`
- Auth: HTTP bearer

Find interview attempts for a report or external application, including prior attempts that remain available.

## Before you call

Use interviews:read. Optional filters include reportId, lifecycle, or both external-reference fields.

**Required scope:** `interviews:read`.

## What happens next

Read each attempt independently and follow nextCursor with identical filters. Keep interview IDs separate from report IDs. Fetch a result for an attempt whose evaluation is ready.

## Recovery

A completed lifecycle is not proof the evaluation is ready. Filter on lifecycle only to select candidate progress; inspect evaluation separately.

[Follow the complete workflow](/integration-interviews/) · [Errors and retries](/api-errors/)

## Query parameters

- `reportId` string
- `lifecycle` 'invited' | 'in_progress' | 'completed' | 'expired' | 'superseded'
- `externalReferenceSource` string
- `externalReferenceId` string
- `limit` integer
- `cursor` string

## Response `200`

Read each attempt independently and follow nextCursor with identical filters. Keep interview IDs separate from report IDs. Fetch a result for an attempt whose evaluation is ready.

- object
  - `data` InterviewPage, required
    - `items` object[], required: Page or batch entries. An empty list is valid; use the cursor or individual item states to decide what happens next.
      - `id` string, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
      - `reportId` string, required: Report ID returned by upload preparation, admission, discovery, or an event. It must belong to the API key's workspace.
      - `interviewSystemVersion` string, required: Assigned interview version captured for this quote or attempt. Existing attempts retain their version.
      - `createdAt` string, date-time, required: UTC creation timestamp in ISO 8601 format.
      - `expiresAt` string, date-time, required: UTC expiration timestamp. For a batch this is the admission deadline, not a cancellation time for already accepted work.
      - `startedAt` string, date-time, nullable, required: UTC time the candidate started the interview; null before start.
      - `completedAt` string, date-time, nullable, required: UTC time the candidate completed the conversation; null before completion. Evaluation may still be pending.
      - `lifecycle` 'invited' | 'in_progress' | 'completed' | 'expired' | 'superseded', required: Candidate progress: invited, in_progress, completed, expired, or superseded. Independent of preparation and evaluation.
      - `preparation` 'queued' | 'processing' | 'ready' | 'failed', required: Interview question-preparation state. ready means the interview content is prepared; it does not mean evaluation is complete.
      - `evaluation` 'not_started' | 'processing' | 'ready' | 'failed', required: Evaluation progress, separate from candidate completion. Read the evaluation when ready.
      - `emailDelivery` 'queued' | 'sent' | 'failed' | 'not_requested', required: Email processing state. sent means provider acceptance, not confirmed inbox delivery; not_requested means your system delivers the link.
      - `resultRevision` string, nullable, required: Identity of the result publication. Store it with resource and attempt IDs to detect a changed evaluation; null before publication.
    - `nextCursor` string, nullable, required: Opaque continuation token. Reuse unchanged with the same filters. List endpoints return null at the end; the event feed always returns a position.

## Other responses

- `400`: Invalid input or cursor
- `401`: Invalid, expired, or revoked API key
- `403`: Disabled organisation or missing scope
- `405`: Method not allowed; consult Allow for supported methods
- `429`: Request limit exceeded
- `500`: Unexpected failure
- `503`: Service unavailable

---

[API](https://skmtc.dev/probbai/apis/probb-ai-customer-api.md) · [All operations](https://skmtc.dev/probbai/apis/probb-ai-customer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/probbai/apis/probb-ai-customer-api/revisions/33a3294530e4?raw)