Skip to content
Registry StackDocsLatest
Search

Query aggregate

POST
/v1/datasets/{dataset_id}/aggregates/{aggregate_id}/query
curl --request POST \
  --url 'https://data.example.test/v1/datasets/example/aggregates/example/query?f=json' \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Data-Purpose: https://demo.example.gov/purpose/demo-review' \
  --data '{ "filters": { "region": [ "north", "south" ] }, "format": "json", "group_by": [ "region" ], "measures": [ "household_count" ] }'

Runs a dataset-scoped aggregate in social_registry with caller-selected measures, group_by dimensions, and configured filters.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
aggregate_id
required
string

Aggregate identifier

dataset_id
required
string

Dataset identifier

Query Parameters

Section titled “Query Parameters”
f
string
Allowed values: json csv sdmx-json

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

Header Parameters

Section titled “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

Request Body

Section titled “Request Body”
Media typeapplication/json
object
filters
object
<= 20 properties
key
additional properties
any
format
string
Allowed values: json csv sdmx-json
group_by
Array<string>
<= 5 items
indicators

Deprecated compatibility alias for measures.

Array<string>
<= 20 items
max_rows

Maximum aggregate observations to return. Results that exceed the cap are truncated and marked incomplete.

integer
>= 1
measures

Measure identifiers to compute. Defaults to the aggregate’s configured measures when omitted.

Array<string>
<= 20 items
temporal

Date bounds applied to the aggregate temporal_field when configured.

object
from
string format: date
to
string format: date

Responses

Section titled “Responses”

200

Section titled “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
id
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
id
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"
      }
    ]
  }
}

400

Section titled “400”

Invalid aggregate query.

Media typeapplication/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"
}

401

Section titled “401”

Missing or invalid bearer credential.

Media typeapplication/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

Section titled “403”

Authenticated principal lacks the scope required for this operation.

Media typeapplication/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"
}

404

Section titled “404”

Aggregate definition not found for this dataset.

Media typeapplication/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

Section titled “default”

Problem Details error response.

Media typeapplication/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"
}