---
title: "Read the matches, with possible matches listed apart and never billed"
method: GET
path: "/v1/finds/{id}/rows"
---

# Read the matches, with possible matches listed apart and never billed

`GET /v1/finds/{id}/rows`

## Request

- Base URL: `https://api.specstream.ai`
- URL: `https://api.specstream.ai/v1/finds/{id}/rows`
- Auth: API key in header `Authorization`

## Path parameters

- `id` string, required

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

Rows page

- object
  - `data` FindRowsPage, required
    - `find_id` string, required
    - `status` 'queued' | 'planning' | 'running' | 'completed' | 'partial' | 'failed' | 'canceled' | 'expired', required
    - `accepted_count` integer, required
    - `rows` AcceptedRow[], required
      - `target_evidence` object, nullable
      - `worded_evidence` object, nullable
      - `lineage` MatchLineage: Evidence-bound reference within an explicitly continued customer lineage.
        - `find_id` string, required
        - `entity_id` string, required
        - `relation` 'same_public_object'
      - `spec_version` 'accepted_row.v1'
      - `entity_id` string, required
      - `ordinal` integer, required
      - `cells` RowCell[], required
        - `column_id` string, required
        - `label` string, required
        - `value` unknown, required
        - `display` string, nullable, required
        - `absence` 'Not published' | 'Couldn't check'
        - `provenance` FieldObservation
          - `entity_id` string, required
          - `field_id` string, required
          - `value` unknown, required
          - `normalized_value` string, nullable, required
          - `source` string, required
          - `source_url` string, nullable, required
          - `observed_at` string, date-time, required
          - `observation_id` string, required
          - `request_hash` string, required
          - `join_method` 'place_id' | 'registrable_domain' | 'e164_phone_locality' | 'address_name' | 'reciprocal_handle' | 'source_declared_link', required
          - `join_confidence` number, nullable
          - `null_reason` 'not_published' | 'blocked_at_source' | 'challenge_page' | 'unreadable' | 'timeout' | 'join_ambiguous' | 'predicate_unknown' | 'internal_failure', required
          - `selected` boolean
          - `value_complete` boolean, nullable
          - `source_record_id` string, nullable
          - `source_pointer` string, nullable
          - `source_response_sha256` string, nullable
          - `source_time` EvidenceTime
            - `contract` 'source-time.v1'
            - `state` 'historical_capture'
            - `captured_at` string, date-time, required
            - `retrieved_at` string, date-time, required
            - `original_url` string, nullable
            - `archive` 'commoncrawl' | 'wayback' | 'arquivo', required
        - `badges` ContactBadge[]
      - `predicates` PredicateEvidence[], required
        - `field_id` string, required
        - `op` 'count_matches' | 'contains' | 'not_contains' | 'has_any' | 'has_all' | 'has_none' | 'before' | 'after' | 'on_or_before' | 'on_or_after' | 'gt' | 'lt' | 'ne' | 'not_in' | 'gte' | 'lte' | 'eq' | 'exists' | 'class_in' | 'in', required
        - `required_value` unknown, required
        - `observed_value` unknown, required
        - `passed` boolean, required
        - `source_label` string, required
        - `source_url` string, nullable, required
        - `observed_at` string, date-time, required
        - `null_reason` 'not_published' | 'blocked_at_source' | 'challenge_page' | 'unreadable' | 'timeout' | 'join_ambiguous' | 'predicate_unknown' | 'internal_failure'
        - `source_ref` PredicateSourceRef: Pointer to a concrete fetch and native record, never a generated group source.
          - `observation_id` string, required
          - `request_hash` string, required
          - `native_record_id` string, nullable
          - `pointer` string, nullable
          - `response_sha256` string, nullable
          - `source_time` EvidenceTime
            - `contract` 'source-time.v1'
            - `state` 'historical_capture'
            - `captured_at` string, date-time, required
            - `retrieved_at` string, date-time, required
            - `original_url` string, nullable
            - `archive` 'commoncrawl' | 'wayback' | 'arquivo', required
        - `record_proof` union
          - RecordCountProof
            - `spec_version` 'record_count_proof.v1'
            - `scope` 'published_source_records'
            - `collection_complete` boolean, required
            - `members_seen` integer, required
            - `lower_bound` integer, required
            - `upper_bound` integer, nullable
            - `matching_pointers` string[], required
            - `unresolved_pointers` string[], required
            - `witnesses` RecordWitness[], required
              - …
            - `witnesses_complete` boolean, required
          - unknown
      - `match_proof` LogicalProof: A proof references evidence, never a fabricated observation for a group. True ANY requires a witnessed branch, true NOT a witnessed false child. Missing evidence stays unknown under every negation. Record-level validation additionally binds each leaf truth to its actual PredicateEvidence entry.
        - `op` 'predicate' | 'all' | 'any' | 'not', required
        - `truth` 'true' | 'false' | 'unknown', required
        - `predicate_index` integer, nullable
        - `children` unknown[]
          - unknown
      - `billable` boolean, required
      - `contact_visibility` 'full' | 'badge' | 'hidden', required
      - `locked` boolean
      - `details` RowCell[]
        - `column_id` string, required
        - `label` string, required
        - `value` unknown, required
        - `display` string, nullable, required
        - `absence` 'Not published' | 'Couldn't check'
        - `provenance` FieldObservation
          - `entity_id` string, required
          - `field_id` string, required
          - `value` unknown, required
          - `normalized_value` string, nullable, required
          - `source` string, required
          - `source_url` string, nullable, required
          - `observed_at` string, date-time, required
          - `observation_id` string, required
          - `request_hash` string, required
          - `join_method` 'place_id' | 'registrable_domain' | 'e164_phone_locality' | 'address_name' | 'reciprocal_handle' | 'source_declared_link', required
          - `join_confidence` number, nullable
          - `null_reason` 'not_published' | 'blocked_at_source' | 'challenge_page' | 'unreadable' | 'timeout' | 'join_ambiguous' | 'predicate_unknown' | 'internal_failure', required
          - `selected` boolean
          - `value_complete` boolean, nullable
          - `source_record_id` string, nullable
          - `source_pointer` string, nullable
          - `source_response_sha256` string, nullable
          - `source_time` EvidenceTime
            - `contract` 'source-time.v1'
            - `state` 'historical_capture'
            - `captured_at` string, date-time, required
            - `retrieved_at` string, date-time, required
            - `original_url` string, nullable
            - `archive` 'commoncrawl' | 'wayback' | 'arquivo', required
        - `badges` ContactBadge[]
    - `possible` PossibleRow[]
      - `spec_version` 'possible_row.v1'
      - `entity_id` string, required
      - `ordinal` integer, required
      - `cells` PossibleCell[], required
        - `column_id` 'identity' | 'link' | 'location', required
        - `label` string, required
        - `value` string, required
      - `conditions` PossibleCondition[], required
        - `condition_id` string, required
        - `label` string, required
        - `status` 'yes' | 'open', required
        - `reason` string, required
        - `quote` string, nullable
        - `source_url` string, nullable
      - `billable` false
    - `flat_rows` object[]
    - `entitlement` string, required
    - `commerce` CommerceData
      - `spec_version` 'commerce.v1'
      - `find_id` string, required
      - `payment_status` string, required
      - `fulfillment_status` string, required
      - `settlement_status` 'none' | 'pending' | 'settled' | 'attention', required
      - `access_state` string, required
      - `access_allowed` boolean, required
      - `next_action` 'wait' | 'retrieve' | 'contact_support' | 'none', required
      - `currency` 'USD'
      - `amount_authorized_cents` integer, required
      - `amount_captured_cents` integer, required
      - `amount_refunded_cents` integer, required
      - `delivered_rows` integer, required
      - `fulfilled_at` string, date-time, nullable, required
      - `access_expires_at` string, date-time, nullable, required
      - `cancel_requested` boolean, required
      - `capacity_offer` CapacityQuoteData, required
        - `pricing_version` 'capacity.v1'
        - `quote_id` string, required
        - `quote_hash` string, required
        - `currency` 'USD' | 'EUR'
        - `maximum_cents` integer, required
        - `expires_at` string, date-time, required
        - `scope` object, required
        - `terms` object, required
          - `unit_cents` integer
          - `contact_unit_cents` integer: Rate for a result delivered with a requested email (or a phone when no phone rate is set); the maximum assumes every result has a contact.
          - `contact_phone_unit_cents` integer: Rate for a result delivered with a requested phone.
          - `check_unit_cents` integer: Charge per imported row resolved and checked, matched or not.
          - `required_check_unit_cents` integer: Charge per company checked for a detail marked as needed that met every condition but lacked it.
          - `required_check_allowance` integer: How many such companies the maximum covers.
          - `related_block_cents` integer: Charge per ten related records past related_included_records in one collection on one result.
          - `undelivered_unit_cents` integer: Missing-result shortfall refund per unit, excluding unused contact contingency.
          - `retail_rate` object
            - `version` string
            - `recheck` boolean
            - `contact_unit_cents` integer, nullable
        - `cost_basis` 'estimated' | 'measured', required
        - `cost_profile_version` string, required
        - `retained_work_cents` 0
        - `existing_execution` object, nullable
        - `can_authorize` boolean
      - `billing_model` 'capacity.v1'
      - `reservation_id` string, required
      - `billed_unit_ids` string[]
      - `billed_units` BilledUnit[]
        - `id` string, required
        - `unit_cents` integer, required
      - `shortfall` Shortfall: A Find that came back short: what was found is delivered, the rest refunded.
        - `requested_units` integer, required
        - `delivered_units` integer, required
        - `refunded_cents` integer, required
    - `next_cursor` string, nullable
    - `delivery` DeliveryReference
      - `find_id` string, required
      - `ast_hash` string, required
      - `snapshot_id` string, required
      - `generated_at` string, date-time, required

## Other responses

- `default`: Error envelope

---

[API](https://skmtc.dev/specstream/apis/specstream-api.md) · [All operations](https://skmtc.dev/specstream/apis/specstream-api/llms.txt) · [OpenAPI document](https://skmtc.dev/specstream/apis/specstream-api/revisions/5a9f51143a13?raw)