Streaming session service (gRPC)#

Provides read access to streaming sessions and their sources.

Endpoints#

Search streaming sessions#

gRPC /nominal.ingest.v2.StreamingSessionService/SearchStreamingSessions

Searches streaming sessions visible to the caller.

Request: SearchStreamingSessionsRequest

page_size integer

Defaults to 100. From 1 to 1,000.

page_token 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

​

dataset_rids StreamingDatasetRidsFilter

​

Fields of StreamingDatasetRidsFilter
dataset_rids array of string

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

source ExactStreamingSourceFilter

​

Fields of ExactStreamingSourceFilter
dataset_rid string required

At most 1,024 characters.

source StreamingSourceAttribution

​

Fields of StreamingSourceAttribution
one of mesh, data_connector, custom required

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
source_dataset_rid string required

At most 1,024 characters.

source_org_rid string required

At most 1,024 characters.

origin_source_label 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.

data_connector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
data_connector_rid string required

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
source_name string

1 to 1,024 characters.

data_bounds_overlap StreamingSessionDataBoundsFilter

​

Fields of StreamingSessionDataBoundsFilter
start string (date-time)

​

end string (date-time)

​

workspace StreamingWorkspaceFilter

​

Fields of StreamingWorkspaceFilter
workspace_rid 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.

is_descending boolean

​

Response: SearchStreamingSessionsResponse

streaming_sessions array of StreamingSession

​

Fields of StreamingSession
streaming_session_rid string

​

dataset_rid 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, data_connector, custom

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
source_dataset_rid string

At most 1,024 characters.

source_org_rid string

At most 1,024 characters.

origin_source_label 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.

data_connector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
data_connector_rid string

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
source_name string

1 to 1,024 characters.

data_bounds 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)

​

points_count integer (int64)

​

created_at string (date-time)

​

last_seen_at string (date-time)

Time of the most recent heartbeat for this session.

completed_at string (date-time)

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

next_page_token string

​

Request

import grpc
from nominal.protos.ingest.v2 import streaming_session_pb2, streaming_session_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
streaming_session_service = streaming_session_pb2_grpc.StreamingSessionServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = streaming_session_pb2.SearchStreamingSessionsRequest(
    page_size=1,
    page_token="<page token>",
    filter={"dataset_rids": {"dataset_rids": ["<dataset rids>"]}},
    sort={"field": "STREAMING_SESSION_SORT_FIELD_CREATED_AT", "is_descending": True},
)
response = streaming_session_service.SearchStreamingSessions(request, metadata=auth)
print(response)

Response

{
  "streaming_sessions": [
    {
      "streaming_session_rid": "<streaming session rid>",
      "dataset_rid": "<dataset rid>",
      "status": "STREAMING_SESSION_STATUS_IN_PROGRESS",
      "source": {
        "mesh": {
          "source_dataset_rid": "<source dataset rid>",
          "source_org_rid": "<source org rid>",
          "origin_source_label": "<origin source label>"
        }
      },
      "data_bounds": {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-01-01T00:00:00Z"
      },
      "points_count": 1,
      "created_at": "2026-01-01T00:00:00Z",
      "last_seen_at": "2026-01-01T00:00:00Z",
      "completed_at": "2026-01-01T00:00:00Z"
    }
  ],
  "next_page_token": "<next page token>"
}

Search streaming sources#

gRPC /nominal.ingest.v2.StreamingSessionService/SearchStreamingSources

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

Request: SearchStreamingSourcesRequest

page_size integer

Defaults to 100. From 1 to 1,000.

page_token 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

​

dataset_rids StreamingDatasetRidsFilter

​

Fields of StreamingDatasetRidsFilter
dataset_rids array of string

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

source ExactStreamingSourceFilter

​

Fields of ExactStreamingSourceFilter
dataset_rid string required

At most 1,024 characters.

source StreamingSourceAttribution

​

Fields of StreamingSourceAttribution
one of mesh, data_connector, custom required

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
source_dataset_rid string required

At most 1,024 characters.

source_org_rid string required

At most 1,024 characters.

origin_source_label 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.

data_connector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
data_connector_rid string required

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
source_name string

1 to 1,024 characters.

workspace StreamingWorkspaceFilter

​

Fields of StreamingWorkspaceFilter
workspace_rid 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

​

last_seen_after 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: SearchStreamingSourcesResponse

streaming_sources array of StreamingSource

​

Fields of StreamingSource
source StreamingSourceAttribution

Absent for unattributed sessions.

Fields of StreamingSourceAttribution
one of mesh, data_connector, custom

​

mesh MeshSourceAttribution

​

Fields of MeshSourceAttribution
source_dataset_rid string

At most 1,024 characters.

source_org_rid string

At most 1,024 characters.

origin_source_label 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.

data_connector DataConnectorSourceAttribution

​

Fields of DataConnectorSourceAttribution
data_connector_rid string

At most 1,024 characters.

custom CustomSourceAttribution

​

Fields of CustomSourceAttribution
source_name string

1 to 1,024 characters.

dataset_rid string

​

session_count integer (int64)

Number of sessions aggregated into this group.

total_points_count integer (int64)

Sum of the points counts across the aggregated sessions.

earliest_created_at string (date-time)

Creation time of the oldest aggregated session.

latest_last_seen_at string (date-time)

Most recent heartbeat time across the aggregated sessions.

merged_data_bounds 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)

​

any_in_progress boolean

True if at least one aggregated session is in progress.

next_page_token string

​

Request

from datetime import datetime, timezone

import grpc
from nominal.protos.ingest.v2 import streaming_session_pb2, streaming_session_pb2_grpc

channel = grpc.secure_channel("api.gov.nominal.io:443", grpc.ssl_channel_credentials())
streaming_session_service = streaming_session_pb2_grpc.StreamingSessionServiceStub(channel)
auth = [("authorization", "Bearer <api key>")]

request = streaming_session_pb2.SearchStreamingSourcesRequest(
    page_size=1,
    page_token="<page token>",
    filter={"dataset_rids": {"dataset_rids": ["<dataset rids>"]}},
    last_seen_after=datetime(2026, 1, 1, tzinfo=timezone.utc),
)
response = streaming_session_service.SearchStreamingSources(request, metadata=auth)
print(response)

Response

{
  "streaming_sources": [
    {
      "source": {
        "mesh": {
          "source_dataset_rid": "<source dataset rid>",
          "source_org_rid": "<source org rid>",
          "origin_source_label": "<origin source label>"
        }
      },
      "dataset_rid": "<dataset rid>",
      "session_count": 1,
      "total_points_count": 1,
      "earliest_created_at": "2026-01-01T00:00:00Z",
      "latest_last_seen_at": "2026-01-01T00:00:00Z",
      "merged_data_bounds": {
        "start": "2026-01-01T00:00:00Z",
        "end": "2026-01-01T00:00:00Z"
      },
      "any_in_progress": true
    }
  ],
  "next_page_token": "<next page token>"
}

Errors#

Errors shows how these errors are sent.

Code

Reason

Message

INVALID_ARGUMENT

STREAMING_SESSION_ERROR_FILTER_TOO_COMPLEX

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

Types#

CustomSourceAttribution#

A caller-named streaming source.

source_name string

1 to 1,024 characters.

DataConnectorSourceAttribution#

A streaming source fed by a data connector.

data_connector_rid 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.

dataset_rid string required

At most 1,024 characters.

source StreamingSourceAttribution

​

MeshSourceAttribution#

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

source_dataset_rid string required

At most 1,024 characters.

source_org_rid string required

At most 1,024 characters.

origin_source_label 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.

dataset_rids 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.

streaming_session_rid string required

​

dataset_rid string required

​

status StreamingSessionStatus required

​

source StreamingSourceAttribution

Absent for unattributed sessions.

data_bounds TimeRange

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

points_count integer (int64)

​

created_at string (date-time) required

​

last_seen_at string (date-time) required

Time of the most recent heartbeat for this session.

completed_at 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

​

dataset_rids StreamingDatasetRidsFilter

​

source ExactStreamingSourceFilter

​

data_bounds_overlap 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

​

is_descending 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.

dataset_rid string required

​

session_count integer (int64)

Number of sessions aggregated into this group.

total_points_count integer (int64)

Sum of the points counts across the aggregated sessions.

earliest_created_at string (date-time) required

Creation time of the oldest aggregated session.

latest_last_seen_at string (date-time) required

Most recent heartbeat time across the aggregated sessions.

merged_data_bounds TimeRange

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

any_in_progress 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, data_connector, custom required

​

mesh MeshSourceAttribution

​

data_connector 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

​

dataset_rids StreamingDatasetRidsFilter

​

source ExactStreamingSourceFilter

​

workspace StreamingWorkspaceFilter

​

and StreamingSourceAndFilter

​

or StreamingSourceOrFilter

​

not StreamingSourceNotFilter

​

StreamingWorkspaceFilter#

Matches sessions or sources whose dataset belongs to the workspace.

workspace_rid 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.