List records

GET

/v1/datasets/{dataset_id}/entities/{entity}/records

curl -sS \
  -H 'Authorization: Bearer $REGISTRY_RELAY_TOKEN' \
  'http://localhost:4242/v1/datasets/social_registry/entities/household/records?limit=10'

import os, httpx

token = os.environ['REGISTRY_RELAY_TOKEN']
resp = httpx.get(
    'http://localhost:4242/v1/datasets/social_registry/entities/household/records',
    params={'limit': 10},
    headers={'Authorization': f'Bearer {token}'}
)
resp.raise_for_status()
page = resp.json()
for row in page['data']:
    print(row)
next_cursor = page['pagination'].get('next_cursor')

List household records from dataset social_registry. Registered household.

Supports pagination via limit+cursor, projection via fields, relationship expansion via expand, and configured filters.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

dataset_id

required

string

Dataset identifier

entity

required

string

Entity name

Query Parameters

limit

integer format: int32

>= 1

Maximum records to return. Capped by the entity’s api.max_limit.

Examples

default

cursor

string

Opaque pagination cursor returned in a prior response’s pagination.next_cursor.

fields

string

Comma-separated list of entity fields to project. Unknown fields are rejected.

expand

string

Allowed values: members

Comma-separated relationships to expand inline. Limited to the entity’s configured allowed_expansions.

string

Filter by exact match on id.

id.in

string

Filter by inclusion in a comma-separated list of id values.

region

string

Filter by exact match on region.

region.in

string

Filter by inclusion in a comma-separated list of region values.

Header Parameters

Data-Purpose

required

string

>= 1 characters

Purpose-of-use IRI or controlled string. When require_purpose_header is set on this entity, the header must be present; a missing value returns 400 auth.purpose_required. The value is always recorded verbatim in the audit trail when present; purpose values are not enforced or validated at the consultation layer. Registry Notary is the purpose-certification layer. Header names are case-insensitive (Data-Purpose and data-purpose are equivalent).

Example

https://demo.example.gov/purpose/demo-review

Responses

200

Successful response

application/json

object

data

required

Array<object>

Registered household.

object

area_geometry

Optional string field.

string | null

required

Required string field.

string

members

Array<object>

object

age

Optional integer field.

integer | null format: int64

household

Registered household.

object

area_geometry

Optional string field.

string | null

required

Required string field.

string

members

Array<object> recursive

region

Optional string field. Codelist: https://example.test/vocab/codelists/Region.

string | null

household_id

required

Required string field.

string

required

Required string field.

string

region

Optional string field. Codelist: https://example.test/vocab/codelists/Region.

string | null

pagination

required

object

has_more

required

True when more pages remain after this one.

boolean

next_cursor

Opaque cursor for the next page; null when has_more is false.

string | null

Example

{
  "data": [
    {
      "area_geometry": "<area_geometry>",
      "id": "01HZX9...",
      "region": "north"
    }
  ],
  "pagination": {
    "has_more": false,
    "next_cursor": null
  }
}

401

Missing or invalid bearer credential.

application/problem+json

RFC 9457 Problem Details, returned for every non-2xx response.

object

code

required

string

detail

required

string

request_id

required

string

status

required

integer format: int32

title

required

string

type

required

string format: uri

key

additional properties

any

Example

{
  "code": "auth.missing_credential",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 401,
  "title": "Missing credential",
  "type": "https://registry-relay.dev/problems/auth/missing_credential"
}

403

Authenticated principal lacks the scope required for this operation.

application/problem+json

RFC 9457 Problem Details, returned for every non-2xx response.

object

code

required

string

detail

required

string

request_id

required

string

status

required

integer format: int32

title

required

string

type

required

string format: uri

key

additional properties

any

Example

{
  "code": "auth.missing_credential",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 401,
  "title": "Missing credential",
  "type": "https://registry-relay.dev/problems/auth/missing_credential"
}

default

Problem Details error response.

application/problem+json

RFC 9457 Problem Details, returned for every non-2xx response.

object

code

required

string

detail

required

string

request_id

required

string

status

required

integer format: int32

title

required

string

type

required

string format: uri

key

additional properties

any

Example

{
  "code": "auth.missing_credential",
  "detail": "no credential provided in Authorization or x-api-key header",
  "request_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
  "status": 401,
  "title": "Missing credential",
  "type": "https://registry-relay.dev/problems/auth/missing_credential"
}