Run aggregate defaults

GET

/v1/datasets/{dataset_id}/aggregates/{aggregate_id}

const url = 'https://data.example.test/v1/datasets/example/aggregates/example?f=json';
const options = {
  method: 'GET',
  headers: {
    'Data-Purpose': 'https://demo.example.gov/purpose/demo-review',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request GET \
  --url 'https://data.example.test/v1/datasets/example/aggregates/example?f=json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Data-Purpose: https://demo.example.gov/purpose/demo-review'

Runs a dataset-scoped aggregate in social_registry with its configured default measures, default group_by, and no optional filters.

Authorizations

bearerAuth
apiKeyAuth

Parameters

Path Parameters

aggregate_id

required

string

Aggregate identifier

dataset_id

required

string

Dataset identifier

Query Parameters

string

Allowed values: json csv sdmx-json

Response format. Use json, csv, or sdmx-json.

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. On ordinary entity and feature routes, the value is recorded verbatim in the audit trail but is not compared to a value allowlist; Registry Notary remains the purpose-certification layer for an offering handoff. Native /v1/consultations/.../execute is separate and validates Data-Purpose against the selected consultation profile contract. Header names are case-insensitive (Data-Purpose and data-purpose are equivalent).

Example

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

x-registry-trust-legal-basis

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:legal_basis:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-trust-consent

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:consent:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-trust-assurance

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:assurance:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-trust-jurisdiction

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:jurisdiction:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-subject-ref

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:subject_ref:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-relationship

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:relationship:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-on-behalf-of

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:on_behalf_of:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-credential-format

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:requested_credential_format:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-source-observed-at-unix-seconds

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:source_observed_at_unix_seconds:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

x-registry-source-observed-age-seconds

string

>= 1 characters

Optional PDP trust context. Relay passes this value to policy evaluation only when the authenticated principal has the exact value-bound registry:trust:source_observed_age_seconds:<value> scope. Without that scope, Relay treats the header as absent. Header names are case-insensitive.

Responses

200

Successful aggregate response.

object

aggregate_id

required

string

completeness

required

object

complete

required

boolean

truncated

required

boolean

dataset_id

required

string

disclosure_control

required

object

method

required

Array<string>

min_cell_size

required

integer

>= 1

query_budget

required

object

scope

required

string

tracked

required

boolean

key

additional properties

any

suppressed_observations

required

integer | null

suppression

required

string

Allowed values: omit mask null

key

additional properties

any

freshness

required

object

as_of

string format: date-time

computed_at

required

string format: date-time

links

required

Array<object>

object

href

required

string

rel

required

string

type

string

key

additional properties

any

observations

required

Array<object>

object

key

additional properties

any

structure

required

object

dimensions

required

Array<object>

object

codelist

string | null format: uri

field

required

string

required

string

label

required

string

measures

required

Array<object>

object

aggregation_method

required

string

column

required

string

decimals

integer | null

definition_uri

string | null format: uri

frequency

string | null

required

string

label

required

string

unit_measure

required

string

unit_multiplier

number | null

Example

{
  "aggregate_id": "households_by_region",
  "completeness": {
    "complete": true,
    "truncated": false
  },
  "dataset_id": "social_registry",
  "disclosure_control": {
    "method": [
      "k-anonymity"
    ],
    "min_cell_size": 2,
    "query_budget": {
      "scope": "none",
      "tracked": false
    },
    "suppressed_observations": 1,
    "suppression": "omit"
  },
  "freshness": {
    "as_of": "2026-05-16T07:55:00Z",
    "computed_at": "2026-05-16T08:00:00Z"
  },
  "links": [],
  "observations": [
    {
      "household_count": 42,
      "region": "north"
    }
  ],
  "structure": {
    "dimensions": [
      {
        "field": "region",
        "id": "region",
        "label": "Region"
      }
    ],
    "measures": [
      {
        "aggregation_method": "count",
        "column": "id",
        "id": "household_count",
        "label": "Households",
        "unit_measure": "households"
      }
    ]
  }
}

SDMX JSON data message for the aggregate result.

object

key

additional properties

any

Example^generated

{}

400

Invalid aggregate query.

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://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

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://id.registrystack.org/problems/registry-relay/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://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

404

Aggregate definition not found for this dataset.

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://id.registrystack.org/problems/registry-relay/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://id.registrystack.org/problems/registry-relay/auth/missing_credential"
}

Run aggregate defaults

Authorizations

Parameters

Path Parameters

Query Parameters

Header Parameters

Example

Responses

200

Example

Examplegenerated

400

Example

401

Example

403

Example

404

Example

default

Example

Example^generated