Skip to main content

List Record Set Records

List records in a record set with page-based pagination. Pass include=values to attach each record's latest cell values with per-cell status and confidence.

List the records (rows) in a record set with offset-based pagination. Each record carries its identity metadata: the document_id it maps to, its ordinal position, an optional record_key, a row-level status, and an aggregate confidence score. Pass include=values to also attach the record's latest cell values keyed by field, each with its own status and confidence. This is the primary way to read structured data out of the value plane.

Unlike the cursor-based pagination used by most list endpoints, record set records use offset-based pagination with page and limit parameters. This is intentional: record sets are table-like structures where random access by page number is a common use case for building paginated table UIs. Records arrive ordered by ordinal ascending, and the pagination block reports the total record count so you can compute page counts up front.

Each values entry is the latest version of that cell: writes append a new cell version rather than mutating in place, so the map always reflects the newest state — extraction first, then any resolution rewrite, then a human review decision, which lands as a fresh version with confidence: 1.0. A record that has no cell for a field simply omits that key from values (and a record with no cells at all returns "values": {}), so treat a missing key as "not written", not as null.

Reads are visibility-filtered, not just tenant-scoped: rows whose source document is hidden from the user who minted your API key by Sources IAM rules are excluded from both pagination.total and every page, so page boundaries always describe the set of rows you can actually see. Records without a document_id are never restricted. Two keys minted by different users can therefore legitimately report different totals for the same record set.

GET/v1/record-sets/{id}/records

Path parameters

id*uuidRecord set UUID. Must belong to your organization.

Query parameters

pageintegerPage number (1-indexed). Default: 1
limitintegerNumber of records per page (1-100). Default: 20
includestringPass "values" to attach each record's latest-version cell values.

Response

Response fields

dataarrayArray of record objects.
data[].idstringRecord UUID.
data[].document_idstring | nullSource document UUID, if the record maps to a document.
data[].ordinalintegerStable row order within the record set (0-based).
data[].record_keystring | nullExternal or customer-defined key, when known (e.g. a contract number).
data[].statusstringRow-level lifecycle state.
data[].confidencenumber | nullAggregate confidence for the row (0-1).
data[].valuesobjectOnly with include=values: map of field_key to the latest cell value.
data[].values[key].valuestring | number | boolean | object | nullThe cell value, typed per the field's data_type. Null for cells held in review.
data[].values[key].statusstringCell lifecycle status: filled, flagged, pending_approval, empty, error, or suppressed.
data[].values[key].confidencenumber | nullPer-cell confidence score (0-1).
pagination.totalintegerTotal number of records in the set.
pagination.pageintegerCurrent page number.
pagination.limitintegerRecords per page.
pagination.has_morebooleanWhether more records exist beyond this page.
linksobjectRelated resource URLs (self, record_set).

curl

curl -s "https://api.talonic.com/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/records?page=1&limit=10&include=values" \
  -H "Authorization: Bearer tlnc_your_api_key"

Response

{
  "data": [
    {
      "id": "f1e2d3c4-b5a6-7890-fedc-ba0987654321",
      "document_id": "d1c2b3a4-e5f6-7890-abcd-ef1234567890",
      "ordinal": 0,
      "record_key": "INV-2024-0042",
      "status": "active",
      "confidence": 0.96,
      "values": {
        "invoice_number": {
          "value": "INV-2024-0042",
          "status": "filled",
          "confidence": 0.97
        },
        "country_code": {
          "value": "DE",
          "status": "flagged",
          "confidence": 0.71
        },
        "total_amount": {
          "value": null,
          "status": "pending_approval",
          "confidence": 0.55
        }
      }
    }
  ],
  "pagination": {
    "total": 142,
    "page": 1,
    "limit": 10,
    "has_more": true
  },
  "links": {
    "self": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/records",
    "record_set": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

curl — jump to an arbitrary page

curl -s "https://api.talonic.com/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/records?page=8&limit=50" \
  -H "Authorization: Bearer tlnc_your_api_key"
A cell with status pending_approval returns value null. Values held in the review queue never leave the API until a reviewer approves them, so treat a null value with pending_approval status as a review holdback, not missing data.

Errors

Error responses

400VALIDATION_ERRORThe id path parameter is not a valid UUID.
401unauthorizedMissing or invalid API key.
404not_foundRecord set not found or does not belong to your organization.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

How do I get the actual cell values for each record?+
Pass `include=values` as a query parameter. Each record then carries a `values` map keyed by field_key, where every entry holds the latest cell value plus its status and confidence. Without the parameter, only row identity metadata is returned.
What does the confidence score mean?+
Confidence is a 0-1 score reflecting how certain the pipeline is about a value. Each cell carries its own confidence, and the record carries an aggregate confidence for the whole row, which is useful for sorting review work by risk.
Why is a cell value null when its status is pending_approval?+
The value is held in the review queue. Cells awaiting approval report their status but withhold the value until a reviewer approves or corrects it, so unapproved data never leaks through the API.
Why does this endpoint use page/limit instead of cursor?+
Record sets are table-like structures where random access by page number is common in table UIs. Offset pagination supports jumping to arbitrary pages, which cursor pagination does not. For pulling the whole set in one call, use the export endpoint instead.
What cell statuses can appear in values?+
filled (a committed value), flagged (a committed value carrying a warning from a resolution flag rule or validation gate), pending_approval (held in review, value withheld), empty (no value found), error, and suppressed. Only filled and flagged carry usable values; treat the rest as non-values with an explanation.
Why do two API keys report different totals for the same set?+
Row visibility is evaluated as the user who minted each key. Sources IAM rules that hide certain source documents from that user exclude the corresponding rows from both the total and the pages, so keys minted by differently-permissioned users can see different slices of the same record set.

Related

Get Record Set
List Record Set Fields
Export Record Set