---
title: "List matches"
method: GET
path: "/v0/matches"
tags: ["Matches"]
---

# List matches

`GET /v0/matches`

## Request

- Base URL: `https://docs.quivr.thevibecompany.co` (the document declares no server; this is the origin it was published from)
- URL: `https://docs.quivr.thevibecompany.co/v0/matches`
- Auth: HTTP bearer

Authorized historical Matches for a Subscription. Stable keyset page cursor, not a Change Cursor. Absence of a Match does not distinguish an evaluator still working from a negative result. A page containing evidence reclaimed by history_retention.alert_detail returns 410 evidence_expired, retryable=false, with resync_url to explicitly resume after the expired Match. Resuming accepts a lost history interval; export evidence before retention expires if needed. Successful pages retain the original evidence and response shape.

## Query parameters

- `subscription_id` string, required
- `page_cursor` string
- `limit` integer

## Response `200`

Successful response

- MatchPage
  - `items` Match[], required
    - `match_id` string, required
    - `subscription_id` string, required
    - `subscription_version_id` string, required
    - `saved_query_id` string, required
    - `saved_query_version_id` string, required
    - `record_id` string, required
    - `record_version_id` string, required
    - `previous_match_id` string
    - `owner` string: Subscription Owner, an opaque end-user reference defined by the client application (for example user-123). Quivr stores, filters and echoes it without interpreting it. At most 128 characters without control characters; none is reserved for the listing filter. A refused owner is 422 invalid_owner, in a creation body as in the listing filter.
    - `evidence` MatchEvidence, required: Immutable evidence for a positive result, including evaluator version/configuration. History retention may expire the entire evidence payload; historical reads then return 410 evidence_expired rather than a successful response with modified evidence. Details are plugin-defined, bounded to 16 KiB and schema-validated by its adapter; core checks referenced Parts. Access is rechecked on reads.
      - `evaluator` EvaluatorConfig, required: Pins an installed evaluator by plugin id and version, and its configuration. Evaluators are the subscription Contributions of the plugins pinned at startup (Plugin Protocol v0). The configuration must satisfy the evaluator's declared configuration schema.
        - `plugin_id` string, required
        - `version` string, required
        - `configuration` object, required
      - `explanation` string, required
      - `part_keys` string[]
      - `details` object
  - `next_page_cursor` string

## Other responses

- `default`: Structured error. Existing /v0 authentication, scope, pagination and idempotency semantics apply.

---

[API](https://skmtc.dev/thevibecompany/apis/quivr-http-api.md) - [All operations](https://skmtc.dev/thevibecompany/apis/quivr-http-api/llms.txt) - [OpenAPI document](https://skmtc.dev/thevibecompany/apis/quivr-http-api/revisions/4f4e30ba8f4e?raw)