Streaming session service#

Provides read access to streaming sessions and their sources.

OpenAPI file: nominal.ingest.v2.json

Endpoints#

Search streaming sessions#

POST /ingest/v2/streaming-sessions/search

Searches streaming sessions visible to the caller.

Body

pageSize integer

Defaults to 100. From 1 to 1,000.

pageToken string

At most 4,096 characters.

filter StreamingSessionSearchFilter

Absent matches every session visible to the caller. The filter tree may contain at most 1000 nodes and 32 levels of nesting.

Fields of StreamingSessionSearchFilter
one of 7 fields required

​

datasetRids StreamingDatasetRidsFilter

​

Fields of StreamingDatasetRidsFilter
datasetRids array of string

At most 1,000 items. No duplicates. Each item: at most 1,024 characters.

source ExactStreamingSourceFilter

​

Fields of ExactStreamingSourceFilter
datasetRid string required

At most 1,024 characters.

source StreamingSourceAttribution

​

Fields of StreamingSourceAttribution
one of mesh, dataConnector, custom required

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
sourceDatasetRid string required

At most 1,024 characters.

sourceOrgRid string required

At most 1,024 characters.

originSourceLabel string

Label for this data’s source on the originating deployment, as that deployment reported it. Opaque: Nominal stores and returns it without interpreting it. It is part of the session’s identity, so writes carrying different labels resolve to different sessions. 1 to 1,024 characters.

dataConnector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
dataConnectorRid string required

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
sourceName string

1 to 1,024 characters.

dataBoundsOverlap StreamingSessionDataBoundsFilter

​

Fields of StreamingSessionDataBoundsFilter
start string (date-time)

​

end string (date-time)

​

workspace StreamingWorkspaceFilter

​

Fields of StreamingWorkspaceFilter
workspaceRid string required

At most 1,024 characters.

and StreamingSessionAndFilter

​

Fields of StreamingSessionAndFilter
filters array of StreamingSessionSearchFilter

1 to 100 items.

or StreamingSessionOrFilter

​

Fields of StreamingSessionOrFilter
filters array of StreamingSessionSearchFilter

1 to 100 items.

not StreamingSessionNotFilter

​

Fields of StreamingSessionNotFilter
filter StreamingSessionSearchFilter required

​

sort StreamingSessionSortOptions

Defaults to created_at descending.

Fields of StreamingSessionSortOptions
field StreamingSessionSortField

​

Values of StreamingSessionSortField
STREAMING_SESSION_SORT_FIELD_UNSPECIFIED

​

STREAMING_SESSION_SORT_FIELD_CREATED_AT

Orders by the time the session was created.

STREAMING_SESSION_SORT_FIELD_DATA_BOUNDS_START

Orders by the start of the session’s data bounds. Sessions with no data bounds are excluded from the results.

isDescending boolean

​

Response

streamingSessions array of StreamingSession

​

Fields of StreamingSession
streamingSessionRid string

​

datasetRid string

​

status StreamingSessionStatus

​

Values of StreamingSessionStatus
STREAMING_SESSION_STATUS_UNSPECIFIED

​

STREAMING_SESSION_STATUS_IN_PROGRESS

The session accepts heartbeats.

STREAMING_SESSION_STATUS_COMPLETED

The server completed the session once it had recorded a minimum number of points and either stopped receiving heartbeats or reached its maximum age. A completed session accepts no further heartbeats; resolving the same source starts a new session.

source StreamingSourceAttribution

Absent for unattributed sessions.

Fields of StreamingSourceAttribution
one of mesh, dataConnector, custom

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
sourceDatasetRid string

At most 1,024 characters.

sourceOrgRid string

At most 1,024 characters.

originSourceLabel string

Label for this data’s source on the originating deployment, as that deployment reported it. Opaque: Nominal stores and returns it without interpreting it. It is part of the session’s identity, so writes carrying different labels resolve to different sessions. 1 to 1,024 characters.

dataConnector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
dataConnectorRid string

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
sourceName string

1 to 1,024 characters.

dataBounds TimeRange

The time range of the data ingested so far. Absent until the first points are recorded.

Fields of TimeRange
start string (date-time)

​

end string (date-time)

​

pointsCount string (int64)

​

createdAt string (date-time)

​

lastSeenAt string (date-time)

Time of the most recent heartbeat for this session.

completedAt string (date-time)

Time the session was completed. Absent while the session is in progress.

nextPageToken string

​

Request

curl -X POST "https://api.gov.nominal.io/api/ingest/v2/streaming-sessions/search" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "pageSize": 1,
  "pageToken": "<page token>",
  "filter": {
    "datasetRids": {
      "datasetRids": [
        "<dataset rids>"
      ]
    }
  },
  "sort": {
    "field": "STREAMING_SESSION_SORT_FIELD_CREATED_AT",
    "isDescending": true
  }
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/ingest/v2/streaming-sessions/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "pageSize": 1,
        "pageToken": "<page token>",
        "filter": {"datasetRids": {"datasetRids": ["<dataset rids>"]}},
        "sort": {
            "field": "STREAMING_SESSION_SORT_FIELD_CREATED_AT",
            "isDescending": True,
        },
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/ingest/v2/streaming-sessions/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "pageSize": 1,
        "pageToken": "<page token>",
        "filter": {"datasetRids": {"datasetRids": ["<dataset rids>"]}},
        "sort": {
            "field": "STREAMING_SESSION_SORT_FIELD_CREATED_AT",
            "isDescending": True,
        },
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/ingest/v2/streaming-sessions/search",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "pageSize": 1,
                "pageToken": "<page token>",
                "filter": {"datasetRids": {"datasetRids": ["<dataset rids>"]}},
                "sort": {
                    "field": "STREAMING_SESSION_SORT_FIELD_CREATED_AT",
                    "isDescending": True,
                },
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "streamingSessions": [
    {
      "streamingSessionRid": "<streaming session rid>",
      "datasetRid": "<dataset rid>",
      "status": "STREAMING_SESSION_STATUS_IN_PROGRESS",
      "source": {
        "mesh": {
          "sourceDatasetRid": "<source dataset rid>",
          "sourceOrgRid": "<source org rid>",
          "originSourceLabel": "<origin source label>"
        }
      },
      "dataBounds": {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-01-01T00:00:00Z"
      },
      "pointsCount": "1",
      "createdAt": "2026-01-01T00:00:00Z",
      "lastSeenAt": "2026-01-01T00:00:00Z",
      "completedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextPageToken": "<next page token>"
}

Search streaming sources#

POST /ingest/v2/streaming-sources/search

Searches streaming sources visible to the caller, aggregated by (source, dataset) and ordered by latest activity descending.

Body

pageSize integer

Defaults to 100. From 1 to 1,000.

pageToken string

At most 4,096 characters.

filter StreamingSourceSearchFilter

Absent matches every source visible to the caller. The filter tree may contain at most 1000 nodes and 32 levels of nesting.

Fields of StreamingSourceSearchFilter
one of 6 fields required

​

datasetRids StreamingDatasetRidsFilter

​

Fields of StreamingDatasetRidsFilter
datasetRids array of string

At most 1,000 items. No duplicates. Each item: at most 1,024 characters.

source ExactStreamingSourceFilter

​

Fields of ExactStreamingSourceFilter
datasetRid string required

At most 1,024 characters.

source StreamingSourceAttribution

​

Fields of StreamingSourceAttribution
one of mesh, dataConnector, custom required

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
sourceDatasetRid string required

At most 1,024 characters.

sourceOrgRid string required

At most 1,024 characters.

originSourceLabel string

Label for this data’s source on the originating deployment, as that deployment reported it. Opaque: Nominal stores and returns it without interpreting it. It is part of the session’s identity, so writes carrying different labels resolve to different sessions. 1 to 1,024 characters.

dataConnector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
dataConnectorRid string required

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
sourceName string

1 to 1,024 characters.

workspace StreamingWorkspaceFilter

​

Fields of StreamingWorkspaceFilter
workspaceRid string required

At most 1,024 characters.

and StreamingSourceAndFilter

​

Fields of StreamingSourceAndFilter
filters array of StreamingSourceSearchFilter

1 to 100 items.

or StreamingSourceOrFilter

​

Fields of StreamingSourceOrFilter
filters array of StreamingSourceSearchFilter

1 to 100 items.

not StreamingSourceNotFilter

​

Fields of StreamingSourceNotFilter
filter StreamingSourceSearchFilter required

​

lastSeenAfter string (date-time)

If present, only sessions last seen strictly after this instant are aggregated; groups whose sessions were all last seen at or before it are omitted.

Response

streamingSources array of StreamingSource

​

Fields of StreamingSource
source StreamingSourceAttribution

Absent for unattributed sessions.

Fields of StreamingSourceAttribution
one of mesh, dataConnector, custom

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
sourceDatasetRid string

At most 1,024 characters.

sourceOrgRid string

At most 1,024 characters.

originSourceLabel string

Label for this data’s source on the originating deployment, as that deployment reported it. Opaque: Nominal stores and returns it without interpreting it. It is part of the session’s identity, so writes carrying different labels resolve to different sessions. 1 to 1,024 characters.

dataConnector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
dataConnectorRid string

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
sourceName string

1 to 1,024 characters.

datasetRid string

​

sessionCount string (int64)

Number of sessions aggregated into this group.

totalPointsCount string (int64)

Sum of the points counts across the aggregated sessions.

earliestCreatedAt string (date-time)

Creation time of the oldest aggregated session.

latestLastSeenAt string (date-time)

Most recent heartbeat time across the aggregated sessions.

mergedDataBounds TimeRange

Union of the data bounds across the aggregated sessions, if any session has data bounds.

Fields of TimeRange
start string (date-time)

​

end string (date-time)

​

anyInProgress boolean

True if at least one aggregated session is in progress.

nextPageToken string

​

Request

curl -X POST "https://api.gov.nominal.io/api/ingest/v2/streaming-sources/search" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "pageSize": 1,
  "pageToken": "<page token>",
  "filter": {
    "datasetRids": {
      "datasetRids": [
        "<dataset rids>"
      ]
    }
  },
  "lastSeenAfter": "2026-01-01T00:00:00Z"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/ingest/v2/streaming-sources/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "pageSize": 1,
        "pageToken": "<page token>",
        "filter": {"datasetRids": {"datasetRids": ["<dataset rids>"]}},
        "lastSeenAfter": "2026-01-01T00:00:00Z",
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/ingest/v2/streaming-sources/search",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "pageSize": 1,
        "pageToken": "<page token>",
        "filter": {"datasetRids": {"datasetRids": ["<dataset rids>"]}},
        "lastSeenAfter": "2026-01-01T00:00:00Z",
    },
)
response.raise_for_status()
print(response.json())

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/ingest/v2/streaming-sources/search",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "pageSize": 1,
                "pageToken": "<page token>",
                "filter": {"datasetRids": {"datasetRids": ["<dataset rids>"]}},
                "lastSeenAfter": "2026-01-01T00:00:00Z",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "streamingSources": [
    {
      "source": {
        "mesh": {
          "sourceDatasetRid": "<source dataset rid>",
          "sourceOrgRid": "<source org rid>",
          "originSourceLabel": "<origin source label>"
        }
      },
      "datasetRid": "<dataset rid>",
      "sessionCount": "1",
      "totalPointsCount": "1",
      "earliestCreatedAt": "2026-01-01T00:00:00Z",
      "latestLastSeenAt": "2026-01-01T00:00:00Z",
      "mergedDataBounds": {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-01-01T00:00:00Z"
      },
      "anyInProgress": true
    }
  ],
  "nextPageToken": "<next page token>"
}

Errors#

Errors shows how these errors are sent.

Each error’s errorName is NominalIngestV2: followed by its name below.

Status

Name

Notes

400

StreamingSessionErrorFilterTooComplex

A streaming search filter may contain at most 1000 nodes and 32 nested levels.

Types#

CustomSourceAttribution#

A caller-named streaming source.

sourceName string

1 to 1,024 characters.

DataConnectorSourceAttribution#

A streaming source fed by a data connector.

dataConnectorRid string required

At most 1,024 characters.

ExactStreamingSourceFilter#

Matches a single streaming source: the sessions on dataset_rid with exactly the given source attribution. An absent source matches only unattributed sessions, not every source.

datasetRid string required

At most 1,024 characters.

source StreamingSourceAttribution

​

MeshSourceAttribution#

A streaming source replicated from a dataset in another organization over mesh.

sourceDatasetRid string required

At most 1,024 characters.

sourceOrgRid string required

At most 1,024 characters.

originSourceLabel string

Label for this data’s source on the originating deployment, as that deployment reported it. Opaque: Nominal stores and returns it without interpreting it. It is part of the session’s identity, so writes carrying different labels resolve to different sessions. 1 to 1,024 characters.

StreamingDatasetRidsFilter#

Matches the given datasets. An empty list matches every dataset.

datasetRids array of string

At most 1,000 items. No duplicates. Each item: at most 1,024 characters.

StreamingSession#

A streaming ingest session on a dataset.

streamingSessionRid string required

​

datasetRid string required

​

status StreamingSessionStatus required

​

source StreamingSourceAttribution

Absent for unattributed sessions.

dataBounds TimeRange

The time range of the data ingested so far. Absent until the first points are recorded.

pointsCount string (int64)

​

createdAt string (date-time) required

​

lastSeenAt string (date-time) required

Time of the most recent heartbeat for this session.

completedAt string (date-time)

Time the session was completed. Absent while the session is in progress.

StreamingSessionAndFilter#

Matches when every child filter matches.

filters array of StreamingSessionSearchFilter

1 to 100 items.

StreamingSessionDataBoundsFilter#

Matches sessions whose data bounds overlap this window. Sessions with no data bounds do not match. If both ends are present, start must not be after end.

start string (date-time)

​

end string (date-time)

​

StreamingSessionNotFilter#

Matches when the child filter does not.

filter StreamingSessionSearchFilter required

​

StreamingSessionOrFilter#

Matches when any child filter matches.

filters array of StreamingSessionSearchFilter

1 to 100 items.

StreamingSessionSearchFilter#

Filter for streaming-session search.

Set exactly one of the fields below.

one of 7 fields required

​

datasetRids StreamingDatasetRidsFilter

​

source ExactStreamingSourceFilter

​

dataBoundsOverlap StreamingSessionDataBoundsFilter

​

workspace StreamingWorkspaceFilter

​

and StreamingSessionAndFilter

​

or StreamingSessionOrFilter

​

not StreamingSessionNotFilter

​

StreamingSessionSortField#

STREAMING_SESSION_SORT_FIELD_UNSPECIFIED

​

STREAMING_SESSION_SORT_FIELD_CREATED_AT

Orders by the time the session was created.

STREAMING_SESSION_SORT_FIELD_DATA_BOUNDS_START

Orders by the start of the session’s data bounds. Sessions with no data bounds are excluded from the results.

StreamingSessionSortOptions#

field StreamingSessionSortField

​

isDescending boolean

​

StreamingSessionStatus#

STREAMING_SESSION_STATUS_UNSPECIFIED

​

STREAMING_SESSION_STATUS_IN_PROGRESS

The session accepts heartbeats.

STREAMING_SESSION_STATUS_COMPLETED

The server completed the session once it had recorded a minimum number of points and either stopped receiving heartbeats or reached its maximum age. A completed session accepts no further heartbeats; resolving the same source starts a new session.

StreamingSource#

Aggregate view of the streaming sessions sharing a single (source, dataset) pair.

source StreamingSourceAttribution

Absent for unattributed sessions.

datasetRid string required

​

sessionCount string (int64)

Number of sessions aggregated into this group.

totalPointsCount string (int64)

Sum of the points counts across the aggregated sessions.

earliestCreatedAt string (date-time) required

Creation time of the oldest aggregated session.

latestLastSeenAt string (date-time) required

Most recent heartbeat time across the aggregated sessions.

mergedDataBounds TimeRange

Union of the data bounds across the aggregated sessions, if any session has data bounds.

anyInProgress boolean

True if at least one aggregated session is in progress.

StreamingSourceAndFilter#

Matches when every child filter matches.

filters array of StreamingSourceSearchFilter

1 to 100 items.

StreamingSourceAttribution#

Where a streaming session’s data comes from.

Set exactly one of the fields below.

one of mesh, dataConnector, custom required

​

mesh MeshSourceAttribution

​

dataConnector DataConnectorSourceAttribution

​

custom CustomSourceAttribution

​

StreamingSourceNotFilter#

Matches when the child filter does not.

filter StreamingSourceSearchFilter required

​

StreamingSourceOrFilter#

Matches when any child filter matches.

filters array of StreamingSourceSearchFilter

1 to 100 items.

StreamingSourceSearchFilter#

Filter for streaming-source search.

Set exactly one of the fields below.

one of 6 fields required

​

datasetRids StreamingDatasetRidsFilter

​

source ExactStreamingSourceFilter

​

workspace StreamingWorkspaceFilter

​

and StreamingSourceAndFilter

​

or StreamingSourceOrFilter

​

not StreamingSourceNotFilter

​

StreamingWorkspaceFilter#

Matches sessions or sources whose dataset belongs to the workspace.

workspaceRid string required

At most 1,024 characters.

TimeRange#

A closed time range.

start must not be after end.

start string (date-time) required

​

end string (date-time) required

​

Page design based on Scalar, MIT License.