Resource metadata service#

The Resource Metadata Service provides common metadata about resources.

OpenAPI file: ResourceMetadataService.json

Endpoints#

List properties and labels#

POST /scout/v1/metadata/list-properties-labels

Returns all existing properties (key value pairs) and labels, which can be used to organize resources such as runs and videos. This legacy bulk-list surface returns string property values only. Use searchPropertyKeys for numeric keys.

Body

resourceTypes array of ResourceType

If omitted, all resource types are included.

Values of ResourceType
RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

Response

properties map of PropertyName to array of string deprecated

Legacy string-only property values. Deprecated: Use the paginated searchPropertyKeys and searchPropertyValues methods instead.

labels array of string

​

Request

curl -X POST "https://api.gov.nominal.io/api/scout/v1/metadata/list-properties-labels" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "resourceTypes": [
    "RUN"
  ],
  "workspaces": [
    "<workspace rid>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/list-properties-labels",
    headers={"Authorization": "Bearer <api key>"},
    json={"resourceTypes": ["RUN"], "workspaces": ["<workspace rid>"]},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/list-properties-labels",
    headers={"Authorization": "Bearer <api key>"},
    json={"resourceTypes": ["RUN"], "workspaces": ["<workspace rid>"]},
)
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/scout/v1/metadata/list-properties-labels",
            headers={"Authorization": "Bearer <api key>"},
            json={"resourceTypes": ["RUN"], "workspaces": ["<workspace rid>"]},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

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

Get metadata usage count#

POST /scout/v1/metadata/usage-count

Returns the count of resources that use a given label or property. The query can match by label, property name (key only), or a full property key+value pair. Counts are scoped to the caller’s accessible workspaces unless specific workspaces are provided.

Body

query MetadataUsageQuery required

​

Set type to "label".

label string

​

Set type to "propertyName".

propertyName string

​

Set type to "property".

property Property

​

Fields of Property
name string required

​

value string required

​

resourceTypes array of ResourceType

If omitted, all resource types are included.

Values of ResourceType
RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

Response

count integer

​

Request

curl -X POST "https://api.gov.nominal.io/api/scout/v1/metadata/usage-count" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "query": {
    "type": "label",
    "label": "<label>"
  }
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/usage-count",
    headers={"Authorization": "Bearer <api key>"},
    json={"query": {"type": "label", "label": "<label>"}},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/usage-count",
    headers={"Authorization": "Bearer <api key>"},
    json={"query": {"type": "label", "label": "<label>"}},
)
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/scout/v1/metadata/usage-count",
            headers={"Authorization": "Bearer <api key>"},
            json={"query": {"type": "label", "label": "<label>"}},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "count": 1
}

Find similar label matches#

POST /scout/v1/metadata/label/find-similar

Given a set of labels, finds similar labels across the specified workspaces and resource types. Includes document count. Useful for detecting unintentional duplicate labels.

Body

resourceTypes array of ResourceType

If omitted, all resource types are included.

Values of ResourceType
RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

labels array of string

​

Response

matches map of Label to array of MatchCount

​

Fields of MatchCount
value string

​

documentCount integer

​

Request

curl -X POST "https://api.gov.nominal.io/api/scout/v1/metadata/label/find-similar" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "resourceTypes": [
    "RUN"
  ],
  "workspaces": [
    "<workspace rid>"
  ],
  "labels": [
    "<label>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/label/find-similar",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "resourceTypes": ["RUN"],
        "workspaces": ["<workspace rid>"],
        "labels": ["<label>"],
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/label/find-similar",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "resourceTypes": ["RUN"],
        "workspaces": ["<workspace rid>"],
        "labels": ["<label>"],
    },
)
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/scout/v1/metadata/label/find-similar",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "resourceTypes": ["RUN"],
                "workspaces": ["<workspace rid>"],
                "labels": ["<label>"],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "matches": {
    "<key>": [
      {
        "value": "<value>",
        "documentCount": 1
      }
    ]
  }
}

Find similar property key matches#

POST /scout/v1/metadata/property/find-similar

Given a set of property keys, finds similar property keys across the specified workspaces and resource types. Includes document count. Useful for detecting unintentional duplicate property keys.

Body

resourceTypes array of ResourceType

If omitted, all resource types are included.

Values of ResourceType
RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

propertyKeys array of string

​

Response

keyMatches map of PropertyName to array of MatchCount

​

Fields of MatchCount
value string

​

documentCount integer

​

Request

curl -X POST "https://api.gov.nominal.io/api/scout/v1/metadata/property/find-similar" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "resourceTypes": [
    "RUN"
  ],
  "workspaces": [
    "<workspace rid>"
  ],
  "propertyKeys": [
    "<property name>"
  ]
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/property/find-similar",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "resourceTypes": ["RUN"],
        "workspaces": ["<workspace rid>"],
        "propertyKeys": ["<property name>"],
    },
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/property/find-similar",
    headers={"Authorization": "Bearer <api key>"},
    json={
        "resourceTypes": ["RUN"],
        "workspaces": ["<workspace rid>"],
        "propertyKeys": ["<property name>"],
    },
)
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/scout/v1/metadata/property/find-similar",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "resourceTypes": ["RUN"],
                "workspaces": ["<workspace rid>"],
                "propertyKeys": ["<property name>"],
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "keyMatches": {
    "<key>": [
      {
        "value": "<value>",
        "documentCount": 1
      }
    ]
  }
}

Search labels#

POST /scout/v1/metadata/search-labels

Returns a paginated list of labels with document usage counts, filterable by resource type, workspace, and search text.

Body

resourceTypes array of ResourceType

If omitted, all resource types are included.

Values of ResourceType
RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

searchText string

Case-insensitive substring filter.

pageSize integer

Maximum number of items per page. Defaults to 1000 if not specified.

pageToken string

Token for fetching the next page of results.

sortBy MetadataSortField required

​

Values of MetadataSortField
ALPHABETICAL

​

USAGE_COUNT

​

PROPERTY_VALUE_COUNT

​

descending boolean

If true, sort in descending order. Defaults to false.

Response

labels array of LabelWithCount

​

Fields of LabelWithCount
label string

​

documentCount integer

​

nextPageToken string

​

Request

curl -X POST "https://api.gov.nominal.io/api/scout/v1/metadata/search-labels" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "sortBy": "ALPHABETICAL"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/search-labels",
    headers={"Authorization": "Bearer <api key>"},
    json={"sortBy": "ALPHABETICAL"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/search-labels",
    headers={"Authorization": "Bearer <api key>"},
    json={"sortBy": "ALPHABETICAL"},
)
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/scout/v1/metadata/search-labels",
            headers={"Authorization": "Bearer <api key>"},
            json={"sortBy": "ALPHABETICAL"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "labels": [
    {
      "label": "<label>",
      "documentCount": 1
    }
  ],
  "nextPageToken": "<token>"
}

Search property keys#

POST /scout/v1/metadata/search-property-keys

Returns a paginated list of string and numeric property keys with typed statistics, filterable by resource type, workspace, and search text. ALPHABETICAL sort pages efficiently at any workspace size. USAGE_COUNT and PROPERTY_VALUE_COUNT rank every key in the workspace, so on large workspaces pass searchText or the request may fail with a 400 MetadataQueryTooBroad error.

Body

resourceTypes array of ResourceType

If omitted, all resource types are included.

Values of ResourceType
RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

searchText string

Case-insensitive substring filter.

pageSize integer

Maximum number of items per page. Defaults to 1000 if not specified.

pageToken string

Token for fetching the next page of results.

sortBy MetadataSortField required

​

Values of MetadataSortField
ALPHABETICAL

​

USAGE_COUNT

​

PROPERTY_VALUE_COUNT

​

descending boolean

If true, sort in descending order. Defaults to false.

Response

propertyKeys array of PropertyKeyWithCount

​

Fields of PropertyKeyWithCount
propertyKey string

​

documentCount integer

Number of documents with either a string or numeric value for this key.

valueCount integer deprecated

Number of distinct string values. Numeric values are intentionally excluded. Deprecated: Retained for backward compatibility. Use string.distinctValueCount instead.

string StringPropertySummary

Present when this key has string values.

Fields of StringPropertySummary
documentCount integer

​

distinctValueCount integer

​

numeric NumericPropertySummary

Present when this key has numeric values.

Fields of NumericPropertySummary
documentCount integer

​

mean number

​

nextPageToken string

​

Request

curl -X POST "https://api.gov.nominal.io/api/scout/v1/metadata/search-property-keys" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "sortBy": "ALPHABETICAL"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/search-property-keys",
    headers={"Authorization": "Bearer <api key>"},
    json={"sortBy": "ALPHABETICAL"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/search-property-keys",
    headers={"Authorization": "Bearer <api key>"},
    json={"sortBy": "ALPHABETICAL"},
)
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/scout/v1/metadata/search-property-keys",
            headers={"Authorization": "Bearer <api key>"},
            json={"sortBy": "ALPHABETICAL"},
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "propertyKeys": [
    {
      "propertyKey": "<property name>",
      "documentCount": 1,
      "valueCount": 1,
      "string": {
        "documentCount": 1,
        "distinctValueCount": 1
      },
      "numeric": {
        "documentCount": 1,
        "mean": 1
      }
    }
  ],
  "nextPageToken": "<token>"
}

Search property values#

POST /scout/v1/metadata/search-property-values

Returns a paginated list of string property values for a given property key with document usage counts, filterable by resource type, workspace, and search text. Numeric values are intentionally excluded; their summary is returned by searchPropertyKeys.

Body

search SearchMetadataRequest required

​

Fields of SearchMetadataRequest
resourceTypes array of ResourceType

If omitted, all resource types are included.

Values of ResourceType
RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

searchText string

Case-insensitive substring filter.

pageSize integer

Maximum number of items per page. Defaults to 1000 if not specified.

pageToken string

Token for fetching the next page of results.

sortBy MetadataSortField required

​

Values of MetadataSortField
ALPHABETICAL

​

USAGE_COUNT

​

PROPERTY_VALUE_COUNT

​

descending boolean

If true, sort in descending order. Defaults to false.

propertyKey string required

​

Response

propertyValues array of PropertyValueWithCount

​

Fields of PropertyValueWithCount
propertyValue string

​

documentCount integer

​

nextPageToken string

​

Request

curl -X POST "https://api.gov.nominal.io/api/scout/v1/metadata/search-property-values" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "search": {
    "sortBy": "ALPHABETICAL"
  },
  "propertyKey": "<property name>"
}'

import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/search-property-values",
    headers={"Authorization": "Bearer <api key>"},
    json={"search": {"sortBy": "ALPHABETICAL"}, "propertyKey": "<property name>"},
)
response.raise_for_status()
print(response.json())

import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/metadata/search-property-values",
    headers={"Authorization": "Bearer <api key>"},
    json={"search": {"sortBy": "ALPHABETICAL"}, "propertyKey": "<property name>"},
)
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/scout/v1/metadata/search-property-values",
            headers={"Authorization": "Bearer <api key>"},
            json={
                "search": {"sortBy": "ALPHABETICAL"},
                "propertyKey": "<property name>",
            },
        ) as response:
            response.raise_for_status()
            print(await response.json())


asyncio.run(main())

Response: 200

{
  "propertyValues": [
    {
      "propertyValue": "<property value>",
      "documentCount": 1
    }
  ],
  "nextPageToken": "<token>"
}

Types#

LabelWithCount#

label string required

​

documentCount integer required

​

MatchCount#

value string required

​

documentCount integer required

​

MetadataSortField#

ALPHABETICAL

​

USAGE_COUNT

​

PROPERTY_VALUE_COUNT

​

MetadataUsageQuery#

Specifies what metadata to count usage for. Exactly one of: a label, a property name (counts all resources with any value for that key), or a full property key+value pair.

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

label string

​

propertyName string

​

property Property

​

NumericPropertySummary#

documentCount integer required

​

mean number required

​

Property#

name string required

​

value string required

​

PropertyKeyWithCount#

propertyKey string required

​

documentCount integer required

Number of documents with either a string or numeric value for this key.

valueCount integer required deprecated

Number of distinct string values. Numeric values are intentionally excluded. Deprecated: Retained for backward compatibility. Use string.distinctValueCount instead.

string StringPropertySummary

Present when this key has string values.

numeric NumericPropertySummary

Present when this key has numeric values.

PropertyValueWithCount#

propertyValue string required

​

documentCount integer required

​

ResourceType#

RUN

​

VIDEO

​

ASSET

​

EVENT

​

DATASET

​

MODULE

​

PROCEDURE_EXECUTION

​

PROCEDURE

​

SAVED_VIEW

​

SearchMetadataRequest#

resourceTypes array of ResourceType

If omitted, all resource types are included.

workspaces array of string (RID)

If omitted, results will come from all workspaces the user belongs to.

searchText string

Case-insensitive substring filter.

pageSize integer

Maximum number of items per page. Defaults to 1000 if not specified.

pageToken string

Token for fetching the next page of results.

sortBy MetadataSortField required

​

descending boolean

If true, sort in descending order. Defaults to false.

StringPropertySummary#

documentCount integer required

​

distinctValueCount integer required

​

Page design based on Scalar, MIT License.