POST/v1/read/sampled

Evaluate attributes on a regular sample grid

operation ID: post_v1_read_sampled

Overview

Evaluate attributes on a regular sample grid. 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 evaluate attributes on a regular sample grid.
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/sampled" \
  --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,
    "interval_ns": 0
  }'

Expected output · 200

Same shape as read/at; instants are start + n*interval strictly before end

Example 200 output

{
  "model_as_of_ns": 0,
  "attributes": [
    {
      "attribute_id": "00000000-0000-4000-8000-000000000001",
      "path": "string",
      "continuity_class": "string",
      "points": [
        {
          "ts_ns": 0,
          "value": 0,
          "quality": 0,
          "interpolated": false
        }
      ],
      "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 evaluate attributes on a regular sample grid. The documented 200 response is same shape as read/at; instants are start + n*interval strictly before end.

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

end_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64

extend_to_nowbooleanoptional

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

interval_nsintegerrequired

format: int64

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_nsintegerrequired

UTC Unix timestamp in nanoseconds

format: int64

unknown fields rejected

Example request body

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

Responses

200Same shape as read/at; instants are start + n*interval strictly before end

application/json

attributesarrayrequired

array

attribute_idstringrequired

format: uuid

continuity_classstringrequired

pathstringrequired

pointsarrayrequired

array

one of

option 1

extendedbooleanoptional

interpolatedbooleanrequired

qualityintegerrequired

minimum: 0

ts_nsany ofrequired

any of

option 1

integer

UTC Unix timestamp in nanoseconds

format: int64

option 2

string

Exact decimal i64 nanoseconds

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

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

no_valuestringrequired
ts_nsany ofrequired: any of
option 1
integer
UTC Unix timestamp in nanoseconds
format: int64
option 2
string
Exact decimal i64 nanoseconds
pattern: ^-?[0-9]+$

unknown fields rejected

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

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",
      "continuity_class": "string",
      "points": [
        {
          "ts_ns": 0,
          "value": 0,
          "quality": 0,
          "interpolated": false
        }
      ],
      "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/sampled`, {
  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,
  "interval_ns": 0
})
});

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.

Evaluate attributes on a regular sample grid

Overview

When to use it

Quick example

How it works

Reference

Parameters

Request body

Responses

Code examples

Related topics