POST/v1/read/summary

Calculate windowed summaries through model bindings

operation ID: post_v1_read_summary

Overview

Calculate windowed summaries through model bindings. Resolved reads turn model selectors into time-series results while preserving binding history, quality, gaps, and provenance.

When to use it

Use it when an application needs to calculate windowed summaries through model bindings.
Use it when a chart, report, analysis, or live view needs model-aware values rather than direct storage rows.

Quick example

Set the base URL and replace generated identifiers or credentials with values from your installation.

cURL

curl --request POST \
  --url "$ORDINATE_URL/v1/read/summary" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "resolve": {
      "select": {
        "kind": "attributes_named",
        "content": {
          "name": "string"
        }
      },
      "scope": {}
    },
    "start_ns": 0,
    "end_ns": 0,
    "fns": [
      "string"
    ]
  }'

Expected output · 200

Window values/null reasons and provenance; suspect or partial data is recorded and flagged on 200

Example 200 output

{
  "model_as_of_ns": 0,
  "attributes": [
    {
      "attribute_id": "00000000-0000-4000-8000-000000000001",
      "path": "string",
      "windows": [
        {
          "start_ns": 0,
          "end_ns": 0,
          "values": {},
          "nulls": {},
          "provenance": {}
        }
      ]
    }
  ],
  "unresolved": [
    {
      "asset_id": "00000000-0000-4000-8000-000000000001",
      "path": "string",
      "requested_name": "string",
      "requested_id": "00000000-0000-4000-8000-000000000001",
      "reason": "string"
    }
  ],
  "provenance": {}
}

The cURL request sends the smallest contract-derived body and asks OrdinateDB to calculate windowed summaries through model bindings. The documented 200 response is window values/null reasons and provenance; suspect or partial data is recorded and flagged on 200.

How it works

The server resolves requested attributes through their time-bounded series bindings, reads the applicable data, then returns the requested representation.

Reference

Required capability: read
Authorization scope: each resolved result

Parameters

No parameters.

Request body

application/json

annotations_cluster_pxintegeroptional

minimum: 0

basisstringoptional

compatstringoptional

compat_optionsany ofoptional

Arbitrary JSON value

any of

option 1

object with arbitrary properties

option 2

array

any items

option 3

string

option 4

number

option 5

integer

option 6

boolean

option 7

null

duration_inany ofoptional

Arbitrary JSON value

any of

option 1

object with arbitrary properties

option 2

array

any items

option 3

string

option 4

number

option 5

integer

option 6

boolean

option 7

null

end_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

string

Exact decimal i64 nanoseconds

pattern: ^-?[0-9]+$

filterstringoptional

fnsarrayrequired

array

string

include_annotationsbooleanoptional

include_episodesany ofoptional

Arbitrary JSON value

any of

option 1

object with arbitrary properties

option 2

array

any items

option 3

string

option 4

number

option 5

integer

option 6

boolean

option 7

null

include_lineagebooleanoptional

resolveobjectrequired

unknown fields rejected

as_of_nsany ofoptional

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null

include_retiredbooleanoptional

rangeany ofoptional

any of

option 1

array · min 2 · max 2

item 1

integer

UTC Unix timestamp in nanoseconds

format: int64

item 2

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

null

scopeobjectrequired

unknown fields rejected

downstream_ofany ofoptional

any of

option 1

assetstringrequired: format: uuid
depthintegeroptional: minimum: 0
viaarrayrequired: array
string

unknown fields rejected

option 2

null

templateany ofoptional

any of

option 1

one of

option 1

contentstringrequired: format: uuid
kindstringrequired

unknown fields rejected

option 2

contentstringrequired
kindstringrequired

unknown fields rejected

option 2

null

underany ofoptional

any of

option 1

one of

option 1

contentstringrequired
kindstringrequired

unknown fields rejected

option 2

contentstringrequired: format: uuid
kindstringrequired

unknown fields rejected

option 2

null

upstream_ofany ofoptional

any of

option 1

assetstringrequired: format: uuid
depthintegeroptional: minimum: 0
viaarrayrequired: array
string

unknown fields rejected

option 2

null

unknown fields rejected

selectone ofrequired

one of

option 1

contentobjectrequired

unknown fields rejected

namestringrequired

unknown fields rejected

kindstringrequired

unknown fields rejected

option 2

contentarrayrequired: array
stringformat: uuid
kindstringrequired

unknown fields rejected

option 3

kindstringrequired

unknown fields rejected

start_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

string

Exact decimal i64 nanoseconds

pattern: ^-?[0-9]+$

timestamp_formatstringoptional

windowany ofoptional

any of

option 1

WindowSpec

one of

option 1

align_nsintegeroptional: Epoch-relative alignment offset in nanoseconds; defaults to zero.
format: int64
kindany JSONrequired
len_nsintegerrequired: Positive fixed-window length in nanoseconds.
format: int64

unknown fields rejected

option 2

kindany JSONrequired
timezonestringrequired: `utc`, `asset`, or an IANA timezone name.
unitstringrequired

unknown fields rejected

option 3

assetsobject | nulloptional
clipbooleanoptional
include_openbooleanoptional
kindany JSONrequired
rolestringoptional
templatesarray | nulloptional: array
string
wherestring | nulloptional

unknown fields rejected

option 2

null

unknown fields rejected

Example request body

{
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  },
  "start_ns": 0,
  "end_ns": 0,
  "fns": [
    "string"
  ]
}

Responses

200Window values/null reasons and provenance; suspect or partial data is recorded and flagged on 200

application/json

attributesarrayrequired

array

attribute_idstringrequired

format: uuid

pathstringrequired

windowsarrayrequired

array

end_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

string

Exact decimal i64 nanoseconds

pattern: ^-?[0-9]+$

nullsobjectrequired

provenanceProvenancerequired

Provenance

chunks_prunedintegeroptional

minimum: 0

clock_suspectbooleanoptional

compat_modestringoptional

computedstringoptional

contains_unknown_arrivalbooleanoptional

lineageLineageoptional

Lineage

rule_idstringrequired

format: uuid

rule_version_rangearrayrequired

min items: 2 · max items: 2

array · min 2 · max 2

integerformat: int64

windowsarrayrequired

array

end_nsintegerrequired: format: int64
evaluated_at_nsintegerrequired: format: int64
rule_versionintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

lossy_rangesarrayoptional

array

LossyRange

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64
tagstringrequired

unknown fields rejected

model_as_of_nsintegeroptional

format: int64

percent_goodnumberoptional

percent_time_filterednumberoptional

provisional_windowsarrayoptional

array

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

quarantined_rangesarrayoptional

array

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

tiers_touchedarrayoptional

array

string

values: hot · warm · cold

window_resolvedRangeNsoptional

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

start_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

string

Exact decimal i64 nanoseconds

pattern: ^-?[0-9]+$

valuesobjectrequired

model_as_of_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

string

Exact decimal i64 nanoseconds

pattern: ^-?[0-9]+$

provenanceProvenancerequired

Provenance

chunks_prunedintegeroptional

minimum: 0

clock_suspectbooleanoptional

compat_modestringoptional

computedstringoptional

contains_unknown_arrivalbooleanoptional

lineageLineageoptional

Lineage

rule_idstringrequired

format: uuid

rule_version_rangearrayrequired

min items: 2 · max items: 2

array · min 2 · max 2

integerformat: int64

windowsarrayrequired

array

end_nsintegerrequired: format: int64
evaluated_at_nsintegerrequired: format: int64
rule_versionintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

lossy_rangesarrayoptional

array

LossyRange

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64
tagstringrequired

unknown fields rejected

model_as_of_nsintegeroptional

format: int64

percent_goodnumberoptional

percent_time_filterednumberoptional

provisional_windowsarrayoptional

array

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

quarantined_rangesarrayoptional

array

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

tiers_touchedarrayoptional

array

string

values: hot · warm · cold

window_resolvedRangeNsoptional

RangeNs

end_nsintegerrequired: format: int64
start_nsintegerrequired: format: int64

unknown fields rejected

unresolvedarrayrequired

array

asset_idany ofrequired: any of
option 1
stringformat: uuid
option 2
null
pathany ofrequired: any of
option 1
string
option 2
null
reasonstringrequired
requested_idany ofrequired: any of
option 1
stringformat: uuid
option 2
null
requested_nameany ofrequired: any of
option 1
string
option 2
null

unknown fields rejected

Example 200 output

{
  "model_as_of_ns": 0,
  "attributes": [
    {
      "attribute_id": "00000000-0000-4000-8000-000000000001",
      "path": "string",
      "windows": [
        {
          "start_ns": 0,
          "end_ns": 0,
          "values": {},
          "nulls": {},
          "provenance": {}
        }
      ]
    }
  ],
  "unresolved": [
    {
      "asset_id": "00000000-0000-4000-8000-000000000001",
      "path": "string",
      "requested_name": "string",
      "requested_id": "00000000-0000-4000-8000-000000000001",
      "reason": "string"
    }
  ],
  "provenance": {}
}

400Invalid read request

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 400 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

401Authentication required

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 401 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

403Read capability is not granted

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 403 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

503Model database is not configured, unavailable, or render capacity is exhausted

application/json

ErrorEnvelope

codestringrequired
correlation_idstringrequired: format: uuid
detailsobjectoptional
errorstringrequired

Example 503 output

{
  "error": "string",
  "code": "account-sealed",
  "correlation_id": "00000000-0000-4000-8000-000000000001"
}

Code examples

These examples are generated from the source contract. Replace the base URL, credentials, identifiers, and minimal generated values for your instance.

JavaScript

const ordinateUrl = "http://localhost:8080";
const token = "<bearer-token>";

const response = await fetch(`${ordinateUrl}/v1/read/summary`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  },
  "start_ns": 0,
  "end_ns": 0,
  "fns": [
    "string"
  ]
})
});

if (!response.ok) {
  throw new Error(`OrdinateDB returned ${response.status}: ${await response.text()}`);
}

const data = await response.json();
console.log(data);

Wire conventions — Understand the prerequisite concepts and transport behavior for this operation.
REST endpoint index — Find other operations in Reads.

Calculate windowed summaries through model bindings

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics