Get Record Set
Retrieve a single record set by UUID: its value plane layer, source kind, lifecycle status, record and field counts, and links to fields, records, and export.
Retrieve a single record set by its UUID. A record set is a table-like collection of structured records at one value plane layer, and this endpoint returns its full metadata: the layer, the source kind and ID, the lifecycle status, record and field counts, and links to the fields, records, and export endpoints. Use it to inspect a record set before fetching its contents.
The layer field tells you where this record set sits in the pipeline progression from structured to product. The kind and source_id fields trace the record set back to the structuring job, resolution run, or assembled product that created it. The record_count and field_count summarize the dataset size without fetching the actual records.
status is active for the live set and superseded for a historical duplicate that a newer set replaced. The platform enforces one active record set per source run and layer, so retries and resumed runs keep writing into the same set — a record set ID you store stays valid across re-runs of the same job. A superseded set remains readable for audit, but treat only the active set as current output.
To follow a set back to what produced it, pair kind with source_id: a structuring_run set points at a structuring job you can read via GET /v1/jobs/{id}, a resolution_run set points at a resolution run under GET /v1/resolutions/{id}, and product-layer sets point at the assembly or data product that built them. The counts are cached summaries maintained as the value plane writes, so while a run is still in flight they can trail the cells already committed by a moment.
Because the read is a single metadata row, this endpoint doubles as a lightweight progress probe: poll it while a pipeline is writing and watch record_count and field_count grow, then switch to the records endpoint once the producing run reports completed. The links object hands a generic client the follow-up URLs ready-made, so an integration can walk from the list, to a set, to its rows without constructing any paths itself.
/v1/record-sets/{id}Path parameters
Response
Response fields
curl
curl -s https://api.talonic.com/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
-H "Authorization: Bearer tlnc_your_api_key"Response
{
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"name": "Resolution Run 2024-10-15",
"layer": "resolved",
"kind": "resolution_run",
"source_id": "b2c3d4e5-f6a7-8901-bcde-f23456789012",
"status": "active",
"record_count": 142,
"field_count": 12,
"created_at": "2024-10-15T11:30:00.000Z",
"links": {
"self": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"fields": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/fields",
"records": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/records",
"export": "/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890/export"
}
}Response (404)
{
"statusCode": 404,
"code": "RESOURCE_NOT_FOUND",
"error": "not_found",
"message": "Record set '11111111-1111-4111-8111-111111111111' not found.",
"retryable": false,
"request_id": "req_467847617a6647d4",
"timestamp": "2026-08-29T11:36:07.930Z",
"path": "/v1/record-sets/11111111-1111-4111-8111-111111111111"
}Errors
Error responses
Frequently asked questions
How do I find which job or resolution produced a record set?+
kind field names the origin type (e.g. structuring_run, resolution_run, data_product) and source_id is the UUID of that entity. Use the corresponding GET endpoint (jobs, resolutions, data products) to retrieve the full source details.What does record_count represent?+
record_count is the total number of records (rows) in the set. For structured and resolved layers, each record typically corresponds to one document. For the product layer, records correspond to assembled output rows.