POST/v1/read/snapshot

Read the current point through model bindings

operation ID: post_v1_read_snapshot

Overview

Read the current point 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 read the current point 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/snapshot" \
  --header "Authorization: Bearer $ORDINATE_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "resolve": {
      "select": {
        "kind": "attributes_named",
        "content": {
          "name": "string"
        }
      },
      "scope": {}
    }
  }'

Expected output · 200

Bare per-attribute array; unbound attributes have snapshot:null

Example 200 output

[
  {
    "attribute_id": "00000000-0000-4000-8000-000000000001",
    "path": "string",
    "snapshot": {
      "ts_ns": 0,
      "value": 0,
      "quality": 0
    },
    "provenance": {}
  }
]

The cURL request sends the smallest contract-derived body and asks OrdinateDB to read the current point through model bindings. The documented 200 response is bare per-attribute array; unbound attributes have snapshot:null.

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

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

Example request body

{
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  }
}

Responses

200Bare per-attribute array; unbound attributes have snapshot:null

application/json

array

attribute_idstringrequired

format: uuid

pathstringrequired

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

snapshotany ofrequired

any of

option 1

qualityintegerrequired

minimum: 0

ts_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64

valueany ofrequired

any of

option 1

number

option 2

integerformat: int64

option 3

boolean

option 4

string

option 5

enum_setstringrequired
ordinalintegerrequired: format: int64

unknown fields rejected

option 2

null

Example 200 output

[
  {
    "attribute_id": "00000000-0000-4000-8000-000000000001",
    "path": "string",
    "snapshot": {
      "ts_ns": 0,
      "value": 0,
      "quality": 0
    },
    "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/snapshot`, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${token}`,
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
  "resolve": {
    "select": {
      "kind": "attributes_named",
      "content": {
        "name": "string"
      }
    },
    "scope": {}
  }
})
});

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.

Read the current point through model bindings

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics