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.

Response

curl -s https://api.talonic.com/v1/record-sets/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \
  -H "Authorization: Bearer tlnc_your_api_key"

{
  "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"
  }
}

{
  "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