Run service#

Runs are collections of channels and metadata from one or more data sources, synchronized over a range of real time, which represents a test event or simulation. These API endpoints let you manage runs in the Nominal app.

OpenAPI file: RunService.json

Endpoints#

Get run with data review summary#

Get all runs properties and labels#

GET /scout/v1/all-runs-properties-labels

Deprecated: Deprecated in favor of MetadataService#listPropertiesAndLabels

This legacy bulk-list surface returns string property values only.

Query parameters

workspaces array of string (RID): If supplied, will return only the properties and labels that are associated with the supplied workspaces. If empty will return all properties and labels for workspaces that the user is permitted to see.

Response

properties map of PropertyName to array of string
labels array of string

Request

curl

curl "https://api.gov.nominal.io/api/scout/v1/all-runs-properties-labels" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/all-runs-properties-labels",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/all-runs-properties-labels",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/all-runs-properties-labels",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "properties": {
    "<key>": [
      "<property value>"
    ]
  },
  "labels": [
    "<label>"
  ]
}

Search runs with data review summary#

Archive run#

PUT /scout/v1/archive-run/{rid}

Soft-deletes a run. Runs still exist in the database but are no longer visible.

Path parameters

rid string (RID) required

Query parameters

includeLinkedWorkbooks boolean: If true, all workbooks that are linked to the run will be archived as well. Defaults to false.

Response

The body is a boolean.

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/scout/v1/archive-run/<rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/scout/v1/archive-run/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/scout/v1/archive-run/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/scout/v1/archive-run/<rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

true

Unarchive run#

PUT /scout/v1/unarchive-run/{rid}

Path parameters

rid string (RID) required

Query parameters

includeLinkedWorkbooks boolean: If true, all auto-archived workbooks that are linked to run will be unarchived as well. Defaults to false.

Response

The body is a boolean.

Request

curl

curl -X PUT "https://api.gov.nominal.io/api/scout/v1/unarchive-run/<rid>" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.put(
    "https://api.gov.nominal.io/api/scout/v1/unarchive-run/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.put(
    "https://api.gov.nominal.io/api/scout/v1/unarchive-run/<rid>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.put(
            "https://api.gov.nominal.io/api/scout/v1/unarchive-run/<rid>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

true

Archive runs#

POST /scout/v1/archive-run

Body

rids array of string (RID)
includeLinkedWorkbooks boolean: If true, all auto-archived workbooks that are linked to run will be unarchived as well. Defaults to false.

Response

No content (HTTP 204).

Request

curl

curl -X POST "https://api.gov.nominal.io/api/scout/v1/archive-run" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "rids": [
    "<run rid>"
  ],
  "includeLinkedWorkbooks": true
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/archive-run",
    headers={"Authorization": "Bearer <api key>"},
    json={"rids": ["<run rid>"], "includeLinkedWorkbooks": True},
)
response.raise_for_status()

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/archive-run",
    headers={"Authorization": "Bearer <api key>"},
    json={"rids": ["<run rid>"], "includeLinkedWorkbooks": True},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/archive-run",
            headers={"Authorization": "Bearer <api key>"},
            json={"rids": ["<run rid>"], "includeLinkedWorkbooks": True},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Unarchive runs#

POST /scout/v1/unarchive-run

Body

rids array of string (RID)
includeLinkedWorkbooks boolean: If true, all auto-archived workbooks that are linked to run will be unarchived as well. Defaults to false.

Response

No content (HTTP 204).

Request

curl

curl -X POST "https://api.gov.nominal.io/api/scout/v1/unarchive-run" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "rids": [
    "<run rid>"
  ],
  "includeLinkedWorkbooks": true
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/unarchive-run",
    headers={"Authorization": "Bearer <api key>"},
    json={"rids": ["<run rid>"], "includeLinkedWorkbooks": True},
)
response.raise_for_status()

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/unarchive-run",
    headers={"Authorization": "Bearer <api key>"},
    json={"rids": ["<run rid>"], "includeLinkedWorkbooks": True},
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/unarchive-run",
            headers={"Authorization": "Bearer <api key>"},
            json={"rids": ["<run rid>"], "includeLinkedWorkbooks": True},
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Get data source ref name and type list#

GET /scout/v1/data-source-ref-names-and-types

Returns the list of ref names that are in use across specified and authorized workspaces.

Query parameters

workspaces array of string (RID): If not empty, will return only the ref names that are associated with the supplied workspaces. If empty will return all ref names for workspaces that the user is permitted to see.

Response

The body is an array of RefNameAndType.

Fields of RefNameAndType

name string

type DataSourceType

Values of DataSourceType

DATASET
CONNECTION
LOGSET
VIDEO
SPATIAL

Request

curl

curl "https://api.gov.nominal.io/api/scout/v1/data-source-ref-names-and-types" \
  -H "Authorization: Bearer <api key>"

requests

import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/data-source-ref-names-and-types",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

httpx

import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/data-source-ref-names-and-types",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/data-source-ref-names-and-types",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

[
  {
    "name": "<data source ref name>",
    "type": "DATASET"
  }
]

Update run attachment#

POST /scout/v1/run/{rid}/attachments

Updates the attachments associated with a run.

Path parameters

rid string (RID) required

Body

attachmentsToAdd array of string (RID)
attachmentsToRemove array of string (RID)

Response

No content (HTTP 204).

Request

curl

curl -X POST "https://api.gov.nominal.io/api/scout/v1/run/<rid>/attachments" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "attachmentsToAdd": [
    "<attachment rid>"
  ],
  "attachmentsToRemove": [
    "<attachment rid>"
  ]
}'

requests

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/run/<rid>/attachments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "attachmentsToAdd": ["<attachment rid>"],
        "attachmentsToRemove": ["<attachment rid>"],
    },
)
response.raise_for_status()

httpx

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/run/<rid>/attachments",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "attachmentsToAdd": ["<attachment rid>"],
        "attachmentsToRemove": ["<attachment rid>"],
    },
)
response.raise_for_status()

aiohttp

import asyncio

import aiohttp


async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/run/<rid>/attachments",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "attachmentsToAdd": ["<attachment rid>"],
                "attachmentsToRemove": ["<attachment rid>"],
            },
        ) as response:
            response.raise_for_status()


asyncio.run(main())

Response: 204

No content.

Errors#

Errors shows how these errors are sent.

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

Status	Name	Notes
400	`AssetNotPresentInRun`
400	`BothAssetAndDataSourcesSpecified`
400	`InvalidConnectionRid`
400	`InvalidDataSourceRefNameType`
400	`InvalidDatasetRid`
400	`InvalidLogSetRid`
400	`InvalidVideoRid`
400	`RunBoundsInverted`
400	`RunPropertiesHaveNullValues`
400	`UnspecifiedAssetForMultiAssetRun`
404	`RunNotFound`
404	`RunNotFoundById`
409	`RefNamesAlreadyUsed`
409	`RunsLocked`	A run under a retention lock is immutable. The runs named here must be unlocked before any of their metadata, data sources, or attachments can be updated. Batch updates are rejected in full rather than partially applied, so this lists every locked run in the request.

Types#

ArchivedStatus#

NOT_ARCHIVED
ARCHIVED

AssetsFilter#

returns runs that match any of the provided assets.

assets array of string (RID)

CheckAlertState#

Set type to the name of one of the other fields, and set only that field.

pendingReview PendingReviewAlertState
closedWithFurtherAction ClosedWithFurtherActionAlertState
closedWithIgnore ClosedWithIgnoreAlertState

CheckAlertStatesFilter#

checkAlertState CheckAlertState required
operator Operator required
threshold integer (int64) required

ClosedWithFurtherActionAlertState#

comment string required
closedBy string (RID) required

ClosedWithIgnoreAlertState#

comment string required
closedBy string (RID) required

ConflictBehavior#

Controls what happens when a rename target property key already exists on a document.

Set type to the name of one of the other fields, and set only that field.

skip SkipOnConflict
overwrite OverwriteOnConflict

CreateRunDataSource#

For write requests, we want to allow for optional fields

dataSource DataSource deprecated: One of dataSource and dataSourceRid must be present. dataSourceRid takes precedence. Deprecated: Use dataSourceRid instead.
dataSourceRid string (RID): One of dataSource and dataSourceRid must be present. dataSourceRid takes precedence.
offset Duration
seriesTags map of TagName to string: Used to resolve logical series for this data source.

CreateRunRequest#

title string required
description string required
startTime UtcTimestamp required
endTime UtcTimestamp
properties map of PropertyName to string deprecated: Deprecated: use typedProperties
typedProperties map of PropertyName to TypedPropertyValue
labels array of string
links array of Link
runPrefix string
dataSources map of DataSourceRefName to CreateRunDataSource
attachments array of string (RID)
asset string (RID) deprecated: Deprecated: Use assets
assets array of string (RID)
workspace string (RID): The workspace in which to create the run. If not provided, the run will be created in the default workspace for the user’s organization, if the default workspace for the organization is configured. All data sources, attachments, and assets must be in the same workspace.

CustomTimeframeFilter#

startTime UtcTimestamp
endTime UtcTimestamp

DataReviewAlertMetrics#

pendingReview integer required
closedWithIgnore integer required
closedWithFurtherAction integer required

DataReviewCheckMetrics#

pendingExecution integer required
executing integer required
passingAutomatic integer required
pendingReview integer required
closedWithIgnore integer required
closedWithFurtherAction integer required
failedToExecutePendingReview integer required
failedToExecuteClosedWithIgnore integer required
failedToExecuteClosedWithFurtherAction integer required

DataReviewMetrics#

checks DataReviewCheckMetrics required
alerts DataReviewAlertMetrics required

DataScope#

dataScopeName string required: The name of the data scope. The name is guaranteed to be be unique within the context of an asset.
dataSource DataSource required
offset Duration
timestampType WeakTimestampType required
seriesTags map of TagName to string: Filters the data source to series matching these tag values. The filtered set of series should be the ones that belong to the asset.

DataScopes#

dataScopes map of DataSourceRefName to DataScope

DataSource#

Set type to the name of one of the other fields, and set only that field.

dataset string (RID)
connection string (RID)
logSet string (RID)
video string (RID)
spatial string (RID)

DataSourceSeriesTag#

name string required
value string required

DataSourceType#

DATASET
CONNECTION
LOGSET
VIDEO
SPATIAL

Duration#

seconds integer (int64) required
nanos integer (int64) required

LabelsFilter#

operator SetOperator required
labels array of string

Link#

title string
url string required

LockStatus#

Whether the run is locked, preventing any changes from being made.

LOCKED
UNLOCKED

MergePropertyValuesForKey#

Merge one or more string values of a property key into a single target value. Merge applies to categorical aliases; continuous numeric values are intentionally excluded.

key string required
source array of string
target string required

MetadataChange#

Set type to the name of one of the other fields, and set only that field.

renameLabel RenameLabel
renamePropertyKey RenamePropertyKey
mergePropertyValuesForKey MergePropertyValuesForKey

NumericPropertyPredicate#

Matches resources that have a numeric value for the named property and whose value satisfies the operator. NEQ excludes resources that lack the property or store a string value under the same name.

name string required
value number required
operator PropertyComparisonOperator required

NumericPropertyRangeOperator#

BETWEEN
NOT_BETWEEN

NumericPropertyRangePredicate#

Inclusive range on a numeric property. At least one bound is required. BETWEEN: min <= x <= max. An absent bound is unbounded on that side. NOT_BETWEEN: x < min OR x > max. An absent bound drops that side. Both operators require a numeric value for name. Missing properties and string values never match. Bounds are closed [min, max] to match the number chip (is between / is not between), not half-open.

name string required
min number
max number
operator NumericPropertyRangeOperator required

Operator#

LEQ
LT
GEQ
GT
EQ

OverwriteOnConflict#

Documents that already have the target property key are included in the rename. The priority list determines which value wins via ordered precedence. Must contain exactly the source keys + target key.

priority array of string

PendingReviewAlertState#

An empty JSON object, {}.

PresetTimeframeDuration#

ALL_TIME
LAST_DAY
LAST_WEEK
LAST_MONTH
LAST_YEAR

PresetTimeframeFilter#

duration PresetTimeframeDuration required

PropertiesFilter#

name string required
values array of string

Property#

name string required
value string required

PropertyComparisonOperator#

EQ
NEQ
GT
GTE
LT
LTE

RefNameAndType#

Scoped to the org-level, intended to help the frontend prevent users from submitting invalid ref names, ex. using a dataset ref name for a connection data source

name string required
type DataSourceType required

RenameLabel#

Rename or merge one or more source labels into a single target label.

source array of string
target string required

RenamePropertyKey#

Rename one or more source property keys to a single target key. Existing values are preserved under the new key. The rename should be skipped in the service for resources w/ conflicting keys.

source array of string
target string required
onConflict ConflictBehavior required

Run#

rid string (RID) required
runNumber integer (int64) required
runPrefix string
title string required
description string required
authorRid string (RID)
startTime UtcTimestamp required
endTime UtcTimestamp
properties map of PropertyName to string deprecated: Deprecated: use typedProperties
typedProperties map of PropertyName to TypedPropertyValue
labels array of string
links array of Link
createdAt string (date-time) required
updatedAt string (date-time) required
assetDataScopesMap map of AssetRid to DataScopes: Map from asset RIDs to their data scopes
assetDataScopes array of DataScope deprecated: Deprecated: Use assetDataScopesMap instead. Will be empty for multi-asset runs.
dataSources map of DataSourceRefName to RunDataSource: Map from refnames to run data sources. Will be empty for multi-asset runs.
attachments array of string (RID)
asset string (RID) deprecated: Deprecated: Use assets
assets array of string (RID)
isArchived boolean required
lockStatus LockStatus: When absent, defaults to UNLOCKED for back-compat.

RunDataReviewEvaluationStatus#

NO_CHECKS_APPLIED
FAILED_TO_EXECUTE
EXECUTING
PENDING_EXECUTION
CLOSED_WITH_FURTHER_ACTION
GENERATED_ALERTS
CLOSED_WITH_IGNORE
PASSING

RunDataReviewSummary#

evaluationStatus RunDataReviewEvaluationStatus required
totalIssueCount integer required
reviewedIssueCount integer required
issuesWithFurtherActionCount integer required
executionErrorCount integer required

RunDataSource#

For read requests, we want to require all fields

dataSource DataSource required
offset Duration required: This offset is used for small time-sync corrections. Notably, it is not the offset to move a relative data source to the start of the run.
refName string required: Included for convenience, duplicated from the key of the map
timestampType WeakTimestampType required
seriesTags map of TagName to string: Used to resolve logical series for this data source.

RunWithDataReviewMetrics#

run Run required
dataReviewMetrics DataReviewMetrics required

RunWithDataReviewSummary#

run Run required
dataReviewSummary RunDataReviewSummary required

SearchQuery#

Set type to the name of one of the other fields, and set only that field.

startTimeInclusive UtcTimestamp deprecated: Deprecated: Use startTime instead
startTime TimeframeFilter
endTimeInclusive UtcTimestamp deprecated: Deprecated: Use endTime instead
endTime TimeframeFilter
timeRange TimeRangeFilter
createdAt TimeframeFilter
exactMatch string: Performs case insensitive exact substring match search on the title.
searchText string
asset string (RID) deprecated: Deprecated: Use getRunsByAsset rather than text-based search
assets AssetsFilter
isSingleAsset boolean: Search for either only single-asset runs (true), or only multi-asset runs (false).
label string deprecated: Deprecated: use labels instead
labels LabelsFilter
property Property deprecated: Deprecated: use properties
propertyKey string: Matches runs that have a property with this key, regardless of value.
properties PropertiesFilter
numericProperty NumericPropertyPredicate: Matches runs using a numeric property comparison.
numericPropertyRange NumericPropertyRangePredicate: Matches runs using an inclusive numeric property range.
dataSourceSeriesTag DataSourceSeriesTag
dataSourceRefName string
dataSource DataSource deprecated: Deprecated: Use dataSourceRefName, rather than searching directly by DataSource.
runNumber integer (int64)
runPrefix string
checkAlertStatesFilter CheckAlertStatesFilter: Search for runs where its aggregated check alert satisfy a given operator and threshold.
archived boolean
and array of SearchQuery
or array of SearchQuery
not SearchQuery
workspace string (RID)
lockStatus LockStatus
datasetRids array of string (RID): Applied as a post-filter to the page returned by unified search. A run matches when any requested dataset is in its data scopes. At most 10 dataset RIDs may be provided.

SetOperator#

AND
OR

SkipOnConflict#

Documents are skipped when: - The target property key already exists on the document, or - Multiple source property keys exist on the document (ambiguous merge). Conflicting document RIDs are returned in the response.

An empty JSON object, {}.

SortField#

NAME
ID
CREATED_AT
START_TIME
END_TIME
PENDING_CHECK_ALERTS

SortKey#

Set type to the name of one of the other fields, and set only that field.

field SortField
property SortProperty: Sort by a property value. Requires a property name, and will always sort null values last.
numericProperty SortProperty: Sort by a numeric property value. String-valued and missing properties are null and always sort last.

SortKeyWithDirection#

sortKey SortKey required
isDescending boolean required

SortOptions#

isDescending boolean required
field SortField deprecated: Deprecated: use SortKey with SortField union type instead
sortKey SortKey: Field to sort by. Includes both field and property-based sorting.
additionalSortKeys array of SortKeyWithDirection: Optional secondary sort keys for tiebreaking. Applied in order after the primary sortKey. Each entry specifies its own sort key and direction. If empty or absent, ties are broken by UUID only.

SortProperty#

name string required

TimeframeFilter#

Set type to the name of one of the other fields, and set only that field.

custom CustomTimeframeFilter
preset PresetTimeframeFilter

TimeRangeFilter#

searches for runs that have at least some intersection with the specified range.

start UtcTimestamp
end UtcTimestamp

TypedPropertyValue#

Typed metadata value. Additional variants may be added as property types expand.

Set type to the name of one of the other fields, and set only that field.

stringValue string
numericValue number

UtcTimestamp#

secondsSinceEpoch integer (int64) required
offsetNanoseconds integer (int64)

WeakTimestampType#

If a CSV data source is still being split, the timestamp type is not known.

ABSOLUTE
RELATIVE
PENDING

Page design based on Scalar, MIT License.

Run service#

Endpoints#

Create run#

Update run#

Get run#

Batch edit run metadata#

Add data sources to run#

Create or update run#

Get run with data review metrics#

Get run with data review summary#

Get run by ID#

Get runs#

Get runs by asset#

Get latest run for assets#

Get all runs properties and labels#

Search runs#

Search runs with data review metrics#

Search runs with data review summary#

Archive run#

Unarchive run#

Archive runs#

Unarchive runs#

Get data source ref name and type list#

Update run attachment#

Errors#

Types#

ArchivedStatus#

AssetsFilter#

CheckAlertState#

CheckAlertStatesFilter#

ClosedWithFurtherActionAlertState#

ClosedWithIgnoreAlertState#

ConflictBehavior#

CreateRunDataSource#

CreateRunRequest#

CustomTimeframeFilter#

DataReviewAlertMetrics#

DataReviewCheckMetrics#

DataReviewMetrics#

DataScope#

DataScopes#

DataSource#

DataSourceSeriesTag#

DataSourceType#

Duration#

LabelsFilter#

Link#

LockStatus#

MergePropertyValuesForKey#

MetadataChange#

NumericPropertyPredicate#

NumericPropertyRangeOperator#

NumericPropertyRangePredicate#

Operator#

OverwriteOnConflict#

PendingReviewAlertState#

PresetTimeframeDuration#

PresetTimeframeFilter#

PropertiesFilter#

Property#

PropertyComparisonOperator#

RefNameAndType#

RenameLabel#

RenamePropertyKey#

Run#

RunDataReviewEvaluationStatus#

RunDataReviewSummary#

RunDataSource#

RunWithDataReviewMetrics#

RunWithDataReviewSummary#

SearchQuery#

SetOperator#

SkipOnConflict#

SortField#

SortKey#

SortKeyWithDirection#

SortOptions#

SortProperty#

TimeframeFilter#

TimeRangeFilter#