---
title: "List reports"
method: GET
path: "/api/v1/reports"
tags: ["Reports"]
---

# List reports

`GET /api/v1/reports`

## Request

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

Find reports in your workspace, reconcile stored application IDs, or backfill your local report index.

## Before you call

Use createdAfter/createdBefore for exclusive time bounds. External-reference filtering requires both source and ID. include=reference adds the reference to each returned report.

**Required scope:** `reports:read`.

## What happens next

Read items and pass nextCursor unchanged to the next request with the same filters. null means the current list is exhausted. Reports are newest first.

## Recovery

Start from the first page if filters change or a cursor is invalid. Newer reports inserted during pagination appear on a fresh first page. Old unsigned cursors are no longer accepted.

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

## Query parameters

- `limit` integer
- `externalReferenceSource` string
- `externalReferenceId` string
- `include` 'reference'
- `cursor` string
- `createdAfter` string, date-time
- `createdBefore` string, date-time

## Response `200`

Read items and pass nextCursor unchanged to the next request with the same filters. null means the current list is exhausted. Reports are newest first.

- object
  - `data` ReportPage, 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.
      - `externalReference` object, nullable: Your application identity: source plus id, unique within the workspace. Prefer an application ID rather than personal information.
        - `source` string, required: Lowercase external-system slug, such as my-ats. Combined with id to identify one application in the workspace.
        - `id` string, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
      - `id` string, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
      - `createdAt` string, date-time, required: UTC creation timestamp in ISO 8601 format.
      - `reportSystemVersion` string, nullable, required: Assigned report version used by the quote or analysis. Can be null for a legacy report.
      - `status` 'awaiting_upload' | 'queued' | 'processing' | 'requires_action' | 'completed' | 'failed', required: Current state of the surrounding resource or finding. Use the documented enum and the operation's workflow explanation.
      - `attemptId` string, nullable, required: Analysis run identity. Retries keep this ID; a new admitted run receives a new ID. Null when no run is available.
      - `code` 'ANALYSIS_FAILED' | 'RESULT_UNAVAILABLE' | 'CANDIDATE_JOB_MISMATCH' | 'UNSUPPORTED_REPORT_VERSION', nullable, required: Stable machine-readable outcome or error code; null when no code applies.
      - `jobDescription` object, required: Role context: inline text or a saved job ID on input; selected role fields on a report response.
        - `id` string, nullable, required: Resource identifier. External-reference IDs are supplied by your system; resource/event IDs are returned by ProBB AI.
        - `title` string, nullable, required: Saved job title, or null if not supplied.
        - `company` string, nullable, required: Company name recorded on the job description; null when not supplied.
      - `candidate` object, required: Public candidate context for this report; unavailable values are null.
        - `name` string, nullable, required: Candidate display name extracted from the supplied material, or null if unavailable.
        - `currentRole` string, nullable, required: Candidate's current role from the resume, or null if unavailable.
      - `result` object, nullable, required: Public evaluation. Null when unavailable, pending, or failed; inspect status rather than interpreting null as a zero score.
        - `score` number, nullable, required: Evidence score from 0 to 10, or null when unavailable. It is not a probability of hiring success.
        - `summary` string, nullable, required: Concise explanation of the result or finding; null when unavailable.
        - `scoreReasoning` string, nullable, required: Explanation of the evidence supporting the score, or null if unavailable.
    - `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)