> ## Documentation Index > Fetch the complete documentation index at: https://docs.retailgrid.io/llms.txt > Use this file to discover all available pages before exploring further. # List current matches and review decisions > Read your organization's current review workspace, including rejected pairs, manual links and reviewer decisions. Read the same current-catalog matching pairs and review statuses as the [review workspace](https://docs.retailgrid.io/price-monitoring/review-matches.md) with your [Public API bearer key](https://docs.retailgrid.io/api-reference/authentication.md). Results include rejected pairs so an uploader can avoid resending them and retain corrected links. ```bash theme={null} curl --fail-with-body --get \ "https://clientapi.retailgrid.io/v1/matching/matches" \ -H "Authorization: Bearer $RETAILGRID_API_KEY" \ --data-urlencode "competitor=shop.example" \ --data-urlencode "limit=50" ``` The verified key selects the organization. Do not supply an organization ID. API-key reads remain available independently of whether the matching dashboard is enabled. ## Select pairs | Query parameter | Meaning | | :- | :- | | `status` | `needs_review`, `auto`, `approved` or `rejected`. Omit it to read all four statuses. | | `competitor` | Exact canonical competitor domain, such as `shop.example`; not a display name or registry ID. Omit it for all competitors. | | `rg_item_id` | Exact catalog item ID. Omit it for all items. | | `limit` | Rows per page: 1–100, default 50. | | `cursor` | Opaque continuation token from `next_cursor`, at most 4096 characters. Omit it to start a traversal. | Rows always use `match_id ASC` ordering. This endpoint has no public sort parameter or observation-date filter. `needs_review` means the pair currently requires review; `auto` means it meets the automatic review policy; `approved` means it is currently approved; `rejected` means it has been rejected or manually removed. These are review-workspace statuses. They do not by themselves establish whether a price qualifies for downstream pricing inputs. ## Read identity and decisions Each entry in `matches` contains its stable `match_id`, current `version`, `rg_item_id` and `competitor_product_id`, plus the item details, competitor, listing URL, relation, method, confidence, manual flag and review metadata. Item details come from the catalog used by the review workspace. Observations and confidence may be `null`. `competitor.id` is the registry ID when available. Legacy rows may have a null ID; use the returned canonical `competitor.domain` to identify and filter those rows. Display names can change and are not identifiers. | Decision field | Meaning | | :- | :- | | `review.status` | Authoritative current review classification. | | `review.action` | Latest applicable review action: `approve`, `reject`, `reopen` or `rematch`; `null` when no review record is available. | | `review.actor`, `review.decided_at`, `review.note` | Attribution, time and note of that review record. The action may precede an evidence change, so always use `review.status` for the current classification. | | `link_decision` | Latest applicable explicit link operation, with `action` (`add` or `remove`), `actor` and `decided_at`; `null` when unavailable. | | `latest_decided_at` | Latest available time from the review and link-operation records; `null` when neither is available. | Decision timestamps include a timezone offset. Missing legacy decision metadata stays unknown; observation time and `matched_at` do not stand in for decision time. `match.is_manual` includes explicit human intent such as approving an automatically produced link. It does not prove the original match was created manually. A rematch leaves the old pair readable as rejected and exposes the replacement with its actual link-add metadata. Do not transfer the old pair's approval to the replacement. ## Follow pages and reconcile changes The response includes `external_org_id`, `matches`, `total`, `counts`, `next_cursor` and `has_more`: * `counts` always contains `needs_review`, `auto`, `approved` and `rejected`, including zeroes. Counts apply the item and competitor filters but omit the selected status filter. * `total` is the count after applying the status filter, or the sum of all four counters when no status is selected. * Counts and totals cover the complete selection, independently of the current page and cursor. * When `has_more` is true, request the returned `next_cursor`. A final page has `has_more: false` and `next_cursor: null`. Keep the same selection while following a cursor: ```bash theme={null} curl --fail-with-body --get \ "https://clientapi.retailgrid.io/v1/matching/matches" \ -H "Authorization: Bearer $RETAILGRID_API_KEY" \ --data-urlencode "competitor=shop.example" \ --data-urlencode "limit=50" \ --data-urlencode "cursor=$NEXT_CURSOR" ``` Process one page at a time and apply pairs idempotently by their identity. Rows and counts are consistent within each response; subsequent pages read current state. This is a live traversal, not an immutable export or an incremental change feed. New or changed pairs that sort before the current cursor appear on a fresh traversal. Start again without `cursor` when reconciling subsequent reviewer decisions; `latest_decided_at` is not a synchronization checkpoint. Cursors are bound to the organization, catalog generation and selection. A catalog-generation change returns `409`; restart without a cursor. Ordinary review decisions and observation updates do not require a traversal restart. Invalid, altered or mismatched cursors are rejected. Invalid query values return `422`; missing, invalid or revoked API keys return `401`. An unavailable upstream workspace returns an error rather than an empty success. Existing [usage limits](https://docs.retailgrid.io/api-reference/usage-limits.md) apply. For an upload reconciliation example, see [Matching uploads](https://docs.retailgrid.io/api-reference/matching/overview.md#reconcile-reviewer-decisions-before-uploading). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.