# NominalClient

## class nominal.core.NominalClient

Bases: [`object`](https://docs.python.org/3/builtins/functions.html#object "(in Python v3.15)")

A client for uploading data and managing resources on the Nominal platform.

### classmethod create(base_url, token, trust_store_path=None, connect_timeout=DEFAULT_CONNECT_TIMEOUT, *, workspace_rid=None, extra_headers=None)

Create a connection to the Nominal platform.

Parameters:
:   - **base_url** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      The URL of the Nominal API platform, e.g. “<https://api.gov.nominal.io/api>”.
    - **token** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      An API token to authenticate with. If None, the token will be looked up in ~/.nominal.yml.
    - **trust_store_path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Path to a PEM CA bundle used to verify TLS for both the HTTP and gRPC
      transports. Defaults to certifi’s bundle. On Windows and Linux, the host’s OS trust
      store (including enterprise/GPO/MDM-installed CAs) is automatically unioned in, so the
      client works on corporate networks with no extra configuration. On macOS, point this at
      your corporate CA PEM if you are behind a TLS-inspecting proxy.
    - **connect_timeout** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)"))

      Timeout for any single request to the Nominal API.
    - **workspace_rid** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional workspace RID to pin the client to for operations that require a single
      workspace. If not provided, those operations resolve a default workspace client-side when needed.
    - **extra_headers** ([*HeaderProvider*](https://dev.nominal.io/python/ref/generated/nominal.core.HeaderProvider.md#nominal.core.HeaderProvider "nominal.core._utils.networking.HeaderProvider") *|* [*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Extra request headers, either as a mapping or HeaderProvider.

Raises:
:   [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If the base URL is malformed, contains user information, or uses HTTP
    without a literal loopback IP. This prevents client construction even for HTTP-only usage.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### create_asset(name, description=None, *, properties=None, labels=())

Create an asset.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the asset.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Human readable description of the asset.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      String or numeric properties for the created asset.
      Integers are stored as floats.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Labels to apply to the asset.

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.
    - [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If no default workspace can be resolved.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the creation request fails.

Return type:
:   [*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset")

### create_attachment(attachment_file, *, description=None, properties=None, labels=())

Return type:
:   [*Attachment*](https://dev.nominal.io/python/ref/generated/nominal.core.Attachment.md#nominal.core.Attachment "nominal.core.attachment.Attachment")

### create_attachment_from_io(attachment, name, file_type=FileTypes.BINARY, description=None, *, properties=None, labels=())

Upload an attachment.
The attachment must be a file-like object in binary mode, e.g. open(path, “rb”) or io.BytesIO.
If the file is not in binary-mode, the requests library blocks indefinitely.

Parameters:
:   - **attachment** ([*BinaryIO*](https://docs.python.org/3/library/typing.html#typing.BinaryIO "(in Python v3.15)"))

      Binary stream to upload; the caller retains ownership.
    - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Attachment title and upload filename. The title is kept as supplied. The upload
      filename preserves any existing extension; otherwise it uses the default from `file_type`.
    - **file_type** ([*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*FileType*](https://dev.nominal.io/python/ref/generated/nominal.core.FileType.md#nominal.core.FileType "nominal.core.filetype.FileType"))

      Default extension and MIME type. The default binary type leaves the upload name unchanged.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional description of the attachment.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Properties to apply to the attachment.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Labels to apply to the attachment.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – An applied default extension is malformed or the upload filename contains unsafe characters.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If creating the attachment from the uploaded file fails.

Return type:
:   [*Attachment*](https://dev.nominal.io/python/ref/generated/nominal.core.Attachment.md#nominal.core.Attachment "nominal.core.attachment.Attachment")

### create_containerized_extractor(name, *, description=None, labels=None, properties=None)

Create a containerized extractor for parsing custom data formats using Nominal-hosted docker images.

A newly created extractor has no container image: register one with
[`ContainerizedExtractor.register_image`](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor.register_image "nominal.core.ContainerizedExtractor.register_image") and activate it before ingesting.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the extractor.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Human-readable description of the extractor.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Labels to set on the extractor.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Key-value properties to set on the extractor.

Returns:
:   The newly created extractor.

Return type:
:   [*ContainerizedExtractor*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor "nominal.core.containerized_extractor.ContainerizedExtractor")

### create_dataset(name, *, description=None, labels=(), properties=None, prefix_tree_delimiter=None, markings=None)

Create an empty dataset.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the dataset to create in Nominal.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Human readable description of the dataset.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Text labels to apply to the created dataset
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      String or numeric properties for the created dataset.
      Integers are stored as floats.
    - **prefix_tree_delimiter** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      If present, the delimiter to represent tiers when viewing channels hierarchically.
    - **markings** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, markings (or marking RIDs) applied to the dataset. Sent as part of
      the creation request rather than applied in a follow-up call.

Returns:
:   Reference to the created dataset in Nominal.

Raises:
:   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.

Return type:
:   [*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset")

### create_empty_video(name, *, description=None, labels=(), properties=None, markings=None)

Create an empty video to append video files to.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the video to create in Nominal
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video to create in nominal
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Labels to apply to the video in nominal
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Properties to apply to the video in nominal
    - **markings** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, markings (or marking RIDs) applied to the video. Sent as part of
      the creation request rather than applied in a follow-up call.

Returns:
:   Handle to the created video

Return type:
:   [*Video*](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video "nominal.core.video.Video")

### create_event(name, type, start, duration=timedelta(), *, description=None, assets=(), properties=None, labels=())

Create an event.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the event.
    - **type** ([*EventType*](https://dev.nominal.io/python/ref/generated/nominal.core.EventType.md#nominal.core.EventType "nominal.core._event_types.EventType"))

      Verbosity level of the event.
    - **start** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Starting timestamp of the event.
    - **duration** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Duration of the event, or zero for an event without duration.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Human readable description of the event.
    - **assets** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Assets or asset RIDs associated with the event.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      String or numeric properties for the created event.
      Integers are stored as floats.
    - **labels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Labels to apply to the event.

Raises:
:   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.

Return type:
:   [*Event*](https://dev.nominal.io/python/ref/generated/nominal.core.Event.md#nominal.core.Event "nominal.core.event.Event")

### create_marking(id, *, description=None, authorized_groups=(), symbol=None, color=None)

Create a marking in the current organization.

Parameters:
:   - **id** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Human-readable identifier for the marking, unique within the organization. Must be
      lowercase alphanumeric characters optionally separated by hyphens, starting with a
      letter, e.g. `export-controlled`.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Human readable description of the marking.
    - **authorized_groups** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      RIDs of the groups authorized to access data sources carrying
      this marking.
    - **symbol** ([*Symbol*](https://dev.nominal.io/python/ref/generated/nominal.core.Symbol.md#nominal.core.Symbol "nominal.core.elements.Symbol") *|* *None*)

      Symbol identifying the marking in the Nominal app.
    - **color** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Six-digit hex color identifying the marking in the Nominal app, e.g. `#cc0000`.
      Either case is accepted; the value is lowercased before being sent.

Returns:
:   Reference to the created marking.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If [`id`](https://docs.python.org/3/builtins/functions.html#id "(in Python v3.15)") is not a valid marking id, or `color` is not a valid hex color.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If creation fails, including when the caller is not an organization admin
      or a marking with this id already exists.

Return type:
:   [*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking")

### create_opsgenie_integration(name, api_key, region, *, description=None)

Create an Opsgenie notification integration in the client’s default workspace.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Display name of the integration.
    - **api_key** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Opsgenie API key.
    - **region** ([*OpsgenieRegion*](https://dev.nominal.io/python/ref/generated/nominal.core.OpsgenieRegion.md#nominal.core.OpsgenieRegion "nominal.core.integration.OpsgenieRegion"))

      Region hosting the Opsgenie integration.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional description.

Returns:
:   The created integration.

Raises:
:   [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If no default workspace can be resolved.

Return type:
:   [*Integration*](https://dev.nominal.io/python/ref/generated/nominal.core.Integration.md#nominal.core.Integration "nominal.core.integration.Integration")

### create_pagerduty_integration(name, routing_key, *, description=None)

Create a PagerDuty notification integration in the client’s default workspace.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Display name of the integration.
    - **routing_key** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      PagerDuty routing key.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional description.

Returns:
:   The created integration.

Raises:
:   [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If no default workspace can be resolved.

Return type:
:   [*Integration*](https://dev.nominal.io/python/ref/generated/nominal.core.Integration.md#nominal.core.Integration "nominal.core.integration.Integration")

### create_run(name: str, start: datetime | int, end: datetime | int | None, description: str | None = None, *, properties: Mapping[str, str | float] | None = None, labels: Sequence[str] = (), links: Sequence[str | tuple[str, str] | LinkDict] = (), attachments: Iterable[Attachment] | Iterable[str] = ()) → Run

### create_run(name: str, start: datetime | int, end: datetime | int | None, description: str | None = None, *, properties: Mapping[str, str | float] | None = None, labels: Sequence[str] = (), links: Sequence[str | tuple[str, str] | LinkDict] = (), attachments: Iterable[Attachment] | Iterable[str] = (), assets: Sequence[Asset | str]) → Run

Create a run, which is is effectively a slice of time across a collection of assets and datasources.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the run to create
    - **start** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)"))

      Starting timestamp of the run to create
    - **end** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Ending timestamp of the run to create, or None for an unbounded run.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional description of the run to create
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      String or numeric properties for the created run.
      Integers are stored as floats.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Optional sequence of labels for the created run
    - **links** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*tuple*](https://docs.python.org/3/builtins/stdtypes.html#tuple "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* [*LinkDict*](https://dev.nominal.io/python/ref/generated/nominal.core.LinkDict.md#nominal.core.LinkDict "nominal.core._utils.api_tools.LinkDict")*]* *|* *None*)

      Link metadata to add to the created run
    - **attachments** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*Attachment*](https://dev.nominal.io/python/ref/generated/nominal.core.Attachment.md#nominal.core.Attachment "nominal.core.attachment.Attachment")*]* *|* [*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Attachments to associate with the created run
    - **assets** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Sequence of assets to associate with the run

Returns:
:   Reference to the created run object

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.
    - [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If no default workspace can be resolved.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the run service request fails.

Return type:
:   [*Run*](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run "nominal.core.run.Run")

### create_secret(name, decrypted_value, description=None, labels=(), properties=None)

Create a secret for the current user

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the secret
    - **decrypted_value** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Plain text value of the secret
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the secret
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Labels for the secret
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Properties for the secret

Return type:
:   [*Secret*](https://dev.nominal.io/python/ref/generated/nominal.core.Secret.md#nominal.core.Secret "nominal.core.secret.Secret")

### create_teams_integration(name, webhook_url, *, description=None)

Create a Microsoft Teams notification integration in the client’s default workspace.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Display name of the integration.
    - **webhook_url** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Teams webhook URL for notifications.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional description.

Returns:
:   The created integration.

Raises:
:   [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If no default workspace can be resolved.

Return type:
:   [*Integration*](https://dev.nominal.io/python/ref/generated/nominal.core.Integration.md#nominal.core.Integration "nominal.core.integration.Integration")

### create_video(name, *, description=None, labels=(), properties=None, markings=None)

Create an empty video to append video files to.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of the video to create in Nominal
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the video to create in nominal
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      Labels to apply to the video in nominal
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Properties to apply to the video in nominal
    - **markings** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      If present, markings (or marking RIDs) applied to the video. Sent as part of
      the creation request rather than applied in a follow-up call.

Returns:
:   Handle to the created video

Return type:
:   [*Video*](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video "nominal.core.video.Video")

### create_webhook_integration(name, webhook_url, *, description=None)

Create a generic webhook notification integration in the client’s default workspace.

Parameters:
:   - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Display name of the integration.
    - **webhook_url** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Destination URL for notifications.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional description.

Returns:
:   The created integration.

Raises:
:   [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If no default workspace can be resolved.

Return type:
:   [*Integration*](https://dev.nominal.io/python/ref/generated/nominal.core.Integration.md#nominal.core.Integration "nominal.core.integration.Integration")

### create_workbook_template(title, *, description=None, labels=None, properties=None, commit_message=None, is_published=False, workspace=WorkspaceSearchType.DEFAULT)

Create an empty workbook template.

Parameters:
:   - **title** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Title of the workbook template
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of the workbook template
    - **labels** ([*list*](https://docs.python.org/3/builtins/stdtypes.html#list "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Labels to attach to the workbook template
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Properties to attach to the workbook template
    - **commit_message** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      An optional message to include with the creation of the template
    - **is_published** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      Whether to publish the template so other users can view it. Defaults to False.
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Workspace to create the workbook template in. Pass [`WorkspaceSearchType.DEFAULT`](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType.DEFAULT "nominal.core.WorkspaceSearchType.DEFAULT") (or None)
      to resolve a single workspace by preferring the client’s configured `workspace_rid` and then falling
      back to a client-side default-workspace lookup.

Returns:
:   The created WorkbookTemplate

Return type:
:   [*WorkbookTemplate*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkbookTemplate.md#nominal.core.WorkbookTemplate "nominal.core.workbook_template.WorkbookTemplate")

### data_review_builder()

Return type:
:   [*DataReviewBuilder*](https://dev.nominal.io/python/ref/generated/nominal.core.DataReviewBuilder.md#nominal.core.DataReviewBuilder "nominal.core.data_review.DataReviewBuilder")

### classmethod from_profile(profile, *, trust_store_path=None, connect_timeout=DEFAULT_CONNECT_TIMEOUT, extra_headers=None)

Create a connection to the Nominal platform from a named profile in the Nominal config.

Parameters:
:   - **profile** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      profile name in the Nominal config.
    - **trust_store_path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Path to a PEM CA bundle used to verify TLS for both the HTTP and gRPC
      transports. Defaults to certifi’s bundle. On Windows and Linux, the host’s OS trust
      store (including enterprise/GPO/MDM-installed CAs) is automatically unioned in, so the
      client works on corporate networks with no extra configuration. On macOS, point this at
      your corporate CA PEM if you are behind a TLS-inspecting proxy.
    - **connect_timeout** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)"))

      Request connection timeout.
    - **extra_headers** ([*HeaderProvider*](https://dev.nominal.io/python/ref/generated/nominal.core.HeaderProvider.md#nominal.core.HeaderProvider "nominal.core._utils.networking.HeaderProvider") *|* [*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Extra request headers, either as a mapping or HeaderProvider.

Raises:
:   [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If the base URL is malformed, contains user information, or uses HTTP
    without a literal loopback IP. This prevents client construction even for HTTP-only usage.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### classmethod from_token(token, base_url=DEFAULT_API_BASE_URL, *, workspace_rid=None, trust_store_path=None, connect_timeout=DEFAULT_CONNECT_TIMEOUT, extra_headers=None, _profile=None)

Create a connection to the Nominal platform from a token.

Parameters:
:   - **token** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Authentication token to use for the connection.
    - **base_url** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      The URL of the Nominal API platform.
    - **workspace_rid** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Optional workspace RID to pin the client to for operations that require a single
      workspace. If not provided, those operations lazily resolve a default workspace when required.
    - **trust_store_path** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Path to a PEM CA bundle used to verify TLS for both the HTTP and gRPC
      transports. Defaults to certifi’s bundle. On Windows and Linux, the host’s OS trust
      store (including enterprise/GPO/MDM-installed CAs) is automatically unioned in, so the
      client works on corporate networks with no extra configuration. On macOS, point this at
      your corporate CA PEM if you are behind a TLS-inspecting proxy.
    - **connect_timeout** ([*timedelta*](https://docs.python.org/3/library/datetime.html#datetime.timedelta "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)"))

      Request connection timeout.
    - **extra_headers** ([*HeaderProvider*](https://dev.nominal.io/python/ref/generated/nominal.core.HeaderProvider.md#nominal.core.HeaderProvider "nominal.core._utils.networking.HeaderProvider") *|* [*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Extra request headers, either as a mapping or HeaderProvider.

Raises:
:   [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If the base URL is malformed, contains user information, or uses HTTP
    without a literal loopback IP. This prevents client construction even for HTTP-only usage.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### get_all_units()

Retrieve list of metadata for all supported units within Nominal

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Unit*](https://dev.nominal.io/python/ref/generated/nominal.core.Unit.md#nominal.core.Unit "nominal.core.unit.Unit")]

### get_asset(rid)

Retrieve an asset by its RID.

Raises:
:   - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no asset has that rid.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If the backend returns multiple assets for the RID.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the retrieval request fails.

Return type:
:   [*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset")

### get_attachment(rid)

Retrieve an attachment by its RID.

Raises:
:   - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no attachment with that RID is accessible.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the retrieval request fails.

Return type:
:   [*Attachment*](https://dev.nominal.io/python/ref/generated/nominal.core.Attachment.md#nominal.core.Attachment "nominal.core.attachment.Attachment")

### get_attachments(rids)

Retrieve attachments by their RIDs.

Raises:
:   - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If any RID does not resolve to an accessible attachment.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If a retrieval request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Attachment*](https://dev.nominal.io/python/ref/generated/nominal.core.Attachment.md#nominal.core.Attachment "nominal.core.attachment.Attachment")]

### get_checklist(rid)

Return type:
:   [*Checklist*](https://dev.nominal.io/python/ref/generated/nominal.core.Checklist.md#nominal.core.Checklist "nominal.core.checklist.Checklist")

### get_commensurable_units(unit_symbol)

Get the list of units that are commensurable (convertible to/from) the given unit symbol.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the units service request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Unit*](https://dev.nominal.io/python/ref/generated/nominal.core.Unit.md#nominal.core.Unit "nominal.core.unit.Unit")]

### get_container_image(rid)

Get a container image by its RID.

Parameters:
:   **rid** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

    RID of the container image to retrieve.

Returns:
:   The requested image, e.g. to poll its `status` after registration.

Return type:
:   [*ContainerImage*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage "nominal.core.container_image.ContainerImage")

### get_containerized_extractor(rid)

Get a containerized extractor by its RID.

Parameters:
:   **rid** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

    RID of the containerized extractor to retrieve.

Returns:
:   The requested extractor, including its active container image (if any).

Return type:
:   [*ContainerizedExtractor*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor "nominal.core.containerized_extractor.ContainerizedExtractor")

### get_data_review(rid)

Retrieve a data review by its RID.

Raises:
:   - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no data review has that rid.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the retrieval request fails.

Return type:
:   [*DataReview*](https://dev.nominal.io/python/ref/generated/nominal.core.DataReview.md#nominal.core.DataReview "nominal.core.data_review.DataReview")

### get_dataset(rid)

Retrieve a dataset by its RID.

Return type:
:   [*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset")

### get_datasets(rids)

Retrieve datasets by their RIDs.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset")]

### get_datasource(rid)

Retrieve a dataset by its RID. Prefer [`get_dataset`](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient.get_dataset "nominal.core.NominalClient.get_dataset") for dataset operations.

Return type:
:   [*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset")

### get_event(rid)

Retrieve an event by its RID.

Raises:
:   [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no event has that rid.

Return type:
:   [*Event*](https://dev.nominal.io/python/ref/generated/nominal.core.Event.md#nominal.core.Event "nominal.core.event.Event")

### get_events(rids)

Retrieve events by their RIDs.

Parameters:
:   **rids** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

    RIDs of the events to retrieve.

Returns:
:   The events that resolved, in the order the backend returned them. RIDs that do not resolve are
    omitted rather than raising, so the result may be shorter than `rids`. Use [`get_event`](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient.get_event "nominal.core.NominalClient.get_event") for a
    single rid that must exist.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Event*](https://dev.nominal.io/python/ref/generated/nominal.core.Event.md#nominal.core.Event "nominal.core.event.Event")]

### get_ingestion_job(rid)

Retrieve an ingest job by its RID.

Return type:
:   [*IngestionJob*](https://dev.nominal.io/python/ref/generated/nominal.core.IngestionJob.md#nominal.core.IngestionJob "nominal.core.ingestion_job.IngestionJob")

### get_integration(rid)

Retrieve a notification integration by RID.

Raises:
:   [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If the integration does not exist or is not accessible.

Return type:
:   [*Integration*](https://dev.nominal.io/python/ref/generated/nominal.core.Integration.md#nominal.core.Integration "nominal.core.integration.Integration")

### get_marking(rid)

Retrieve a marking by RID.

Raises:
:   - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no marking with the given RID exists.
    - [**NominalPermissionDeniedError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalPermissionDeniedError.md#nominal.exceptions.NominalPermissionDeniedError "nominal.exceptions.NominalPermissionDeniedError") – If the caller cannot read it.

Return type:
:   [*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking")

### get_marking_by_id(id)

Retrieve a marking by its human-readable id, unique within the organization.

Raises:
:   - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If [`id`](https://docs.python.org/3/builtins/functions.html#id "(in Python v3.15)") is not a valid marking id.
    - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no marking with the given id exists.
    - [**NominalPermissionDeniedError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalPermissionDeniedError.md#nominal.exceptions.NominalPermissionDeniedError "nominal.exceptions.NominalPermissionDeniedError") – If the caller cannot read it.

Return type:
:   [*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking")

### get_or_create_asset_by_properties(properties, *, name, description=None, labels=())

Searches for an asset using using properties. If no assets returned, create one.
:   If multiple assets returned, throw error.

Parameters:
:   - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]*)

      String or numeric properties used to search for or create the asset.
      Integer values are converted to floats.
    - **name** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      Name of asset to be used if creation is necessary.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Description of asset to be used if creation is necessary.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]*)

      a sequence of labels to use when if creation is necessary.

Returns:
:   The existing or newly created asset.

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.
    - [**ValueError**](https://docs.python.org/3/builtins/exceptions.html#ValueError "(in Python v3.15)") – If multiple assets match the properties.
    - [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If no default workspace can be resolved.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If searching for or creating the asset fails.

Return type:
:   [*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset")

### get_run(rid)

Retrieve a run by its RID.

Raises:
:   - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no run has that RID.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the retrieval request fails.

Return type:
:   [*Run*](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run "nominal.core.run.Run")

### get_secret(rid)

Retrieve a secret by RID.

Raises:
:   [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – If no secret with the given RID exists or it is not accessible to the user.

Return type:
:   [*Secret*](https://dev.nominal.io/python/ref/generated/nominal.core.Secret.md#nominal.core.Secret "nominal.core.secret.Secret")

### get_unit(unit_symbol)

Get details of the given unit symbol, or none if the symbol is not recognized by Nominal.

Parameters:
:   **unit_symbol** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

    Symbol of the unit to get metadata for.

    **Note:** This currently requires that units are formatted as laid out in
    the latest UCUM standards (see <https://ucum.org/ucum>).

Returns:
:   Resolved unit metadata if the symbol is valid and supported by Nominal, or None
    if no such unit symbol matches.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the units service request fails for a reason other than an
    unrecognized symbol.

Return type:
:   [*Unit*](https://dev.nominal.io/python/ref/generated/nominal.core.Unit.md#nominal.core.Unit "nominal.core.unit.Unit") | *None*

### get_user(user_rid=None)

Retrieve the specified user.

Parameters:
:   **user_rid** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

    Rid of the user to retrieve

Returns:
:   Details on the requested user, or the current user if no user rid is provided.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the user request fails, including when the user does not exist or is not a member or
    guest of the caller’s organization.

Return type:
:   [*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User")

### get_video(rid)

Retrieve a video by its RID.

Return type:
:   [*Video*](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video "nominal.core.video.Video")

### get_videos(rids)

Retrieve videos by their RID.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Video*](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video "nominal.core.video.Video")]

### get_workbook(rid)

Gets the given workbook by rid.

Return type:
:   [*Workbook*](https://dev.nominal.io/python/ref/generated/nominal.core.Workbook.md#nominal.core.Workbook "nominal.core.workbook.Workbook")

### get_workbook_template(rid)

Gets the given workbook template by rid.

Return type:
:   [*WorkbookTemplate*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkbookTemplate.md#nominal.core.WorkbookTemplate "nominal.core.workbook_template.WorkbookTemplate")

### get_workspace(workspace_rid=None)

Get workspace via given RID, or the default workspace if no RID is provided.

Parameters:
:   **workspace_rid** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

    If provided, the RID of the workspace to retrieve and validate. If None, resolves the
    client’s default workspace by first using the configured `workspace_rid` (for example from
    `config.yml`) and then falling back to a client-side default-workspace lookup.

Returns:
:   Returns details about the requested workspace.

Raises:
:   - [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – Raises a NominalConfigError if no workspace provided and no default workspace can
      be resolved.
    - [**NominalNotFoundError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalNotFoundError.md#nominal.exceptions.NominalNotFoundError "nominal.exceptions.NominalNotFoundError") – The requested workspace does not exist or is not accessible to the user (the
      backend does not distinguish the two).

Return type:
:   [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace")

### list_integrations(*, workspace=None)

List available notification integrations across all result pages.

Parameters:
:   **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

    Workspace to search. None uses the client’s default; [`WorkspaceSearchType.ALL`](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType.ALL "nominal.core.WorkspaceSearchType.ALL")
    searches all accessible workspaces.

Returns:
:   Integrations visible in the selected workspace scope.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Integration*](https://dev.nominal.io/python/ref/generated/nominal.core.Integration.md#nominal.core.Integration "nominal.core.integration.Integration")]

### list_streaming_checklists(asset=None)

List all Streaming Checklists.

Parameters:
:   **asset** ([*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

    if provided, only return checklists associated with the given asset.

Returns:
:   All streaming checklist RIDs that match the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")]

### list_workspaces()

Return all workspaces visible to the current user.

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the workspace service request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace")]

### search_assets(search_text=None, *, labels=None, properties=None, exact_substring=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for assets meeting the specified filters.
Filters are ANDed together, e.g. `(asset.label == label) AND (asset.search_text =~ field)`

Parameters:
:   - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Fuzzy match: tokenized across name, description, labels, and properties, with additional
      substring and similarity matching on name and description, so results need not contain the given
      text verbatim.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A sequence of labels that must ALL be present on a asset to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      Property equalities that must ALL match. String values match string properties;
      numeric values match numeric properties, without coercing strings to numbers.
      Integer values are converted to floats.
    - **exact_substring** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Case-insensitive substring of the asset’s name, description, labels, or properties.
      Unlike `search_text`, results always contain the given text verbatim.
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All assets which match all of the provided conditions

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.
    - [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If the default workspace is requested but cannot be resolved.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If a search request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset")]

### search_checklists(search_text=None, labels=None, properties=None, author=None, assignee=None, workspace=WorkspaceSearchType.DEFAULT, *, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for checklists meeting the specified filters.
Filters are ANDed together, e.g. `(checklist.label == label) AND (checklist.search_text =~ field)`

Parameters:
:   - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      case-insensitive search for any of the keywords in all string fields
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A sequence of labels that must ALL be present on a checklist to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A mapping of key-value pairs that must ALL be present on a checklist to be included.
    - **author** ([*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Author of checklists to search for
    - **assignee** ([*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Assignee of checklists to search for
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Checklist*](https://dev.nominal.io/python/ref/generated/nominal.core.Checklist.md#nominal.core.Checklist "nominal.core.checklist.Checklist")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All checklists which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Checklist*](https://dev.nominal.io/python/ref/generated/nominal.core.Checklist.md#nominal.core.Checklist "nominal.core.checklist.Checklist")]

### search_container_images(*, tag=None, status=None, extractor=None, workspace=WorkspaceSearchType.DEFAULT)

Search for container images meeting the specified filters.

Filters are ANDed together, e.g. `(image.tag == tag) AND (image.status == status)`.

Parameters:
:   - **tag** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      If provided, only include images registered with this tag.
    - **status** ([*ContainerImageStatus*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImageStatus.md#nominal.core.ContainerImageStatus "nominal.core.container_image.ContainerImageStatus") *|* *None*)

      If provided, only include images with this status.
    - **extractor** ([*ContainerizedExtractor*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor "nominal.core.containerized_extractor.ContainerizedExtractor") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      If provided, only include images filtered to this containerized extractor
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Workspace to search within (the client’s default workspace if not provided).

Returns:
:   All container images matching all of the provided filters.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*ContainerImage*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerImage.md#nominal.core.ContainerImage "nominal.core.container_image.ContainerImage")]

### search_containerized_extractors(*, include_archived=False, file_extension=None, labels=None, properties=None, workspace=WorkspaceSearchType.DEFAULT)

Search for containerized extractors meeting the specified filters.

Parameters:
:   - **include_archived** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If true, include archived extractors in the results.
    - **file_extension** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      If provided, only include extractors whose active image declares an input
      accepting files with this suffix (e.g. “csv” — no leading dot).
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Only include extractors carrying every requested label.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Only include extractors carrying every requested name/value pair.
      Extractors may carry additional labels and properties.
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Workspace to search within (the client’s default workspace if not provided).

Returns:
:   All extractors matching all of the provided filters.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*ContainerizedExtractor*](https://dev.nominal.io/python/ref/generated/nominal.core.ContainerizedExtractor.md#nominal.core.ContainerizedExtractor "nominal.core.containerized_extractor.ContainerizedExtractor")]

### search_data_reviews(assets=None, runs=None, *, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for data reviews meeting the specified filters.
Filters are ANDed together, e.g. `(data_review.asset == asset) AND (data_review.run == run)`

Parameters:
:   - **assets** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      List of assets that must be associated with a data review to be included.
    - **runs** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Run*](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run "nominal.core.run.Run") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      List of runs that must be associated with a data review to be included.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter by archive status. Defaults to NOT_ARCHIVED.

Returns:
:   All data reviews which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*DataReview*](https://dev.nominal.io/python/ref/generated/nominal.core.DataReview.md#nominal.core.DataReview "nominal.core.data_review.DataReview")]

### search_dataset_files(dataset, *, start=None, end=None, file_tags=None)

Search for dataset files within a specific dataset.
Filters are ANDed together. Time range uses overlap semantics: a file is included if its
time range overlaps with [start, end], i.e. `file.end >= start AND file.start <= end`.

Parameters:
:   - **dataset** ([*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)"))

      The dataset (or its RID) to search for files within.
    - **start** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Inclusive lower bound of the search window. Files whose time range ends at or
      after this timestamp are returned — including files that started before `start`
      but still overlap the window. Files ending entirely before `start` are excluded.

      **Note:** Truncated to whole seconds — sub-second precision is dropped.
    - **end** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Inclusive upper bound of the search window. Files whose time range starts at or
      before this timestamp are returned — including files that end after `end` but
      still overlap the window. Files starting entirely after `end` are excluded.

      **Note:** Truncated to whole seconds — sub-second precision is dropped.
    - **file_tags** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A mapping of key-value tag pairs that must ALL be present on a dataset file to be included.

Returns:
:   All dataset files within the given dataset which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*DatasetFile*](https://dev.nominal.io/python/ref/generated/nominal.core.DatasetFile.md#nominal.core.DatasetFile "nominal.core.dataset_file.DatasetFile")]

### search_datasets(*, exact_match=None, search_text=None, labels=None, properties=None, before=None, after=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for datasets meeting the specified filters.
Filters are ANDed together, e.g. `(dataset.label == label) AND (dataset.property == property)`

Parameters:
:   - **exact_match** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Case-insensitive substring of the dataset’s name, description, labels, or properties.
    - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Fuzzy match: tokenized across name, description, labels, and properties, with additional
      substring and similarity matching on name and description, so results need not contain the given
      text verbatim.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A sequence of labels that must ALL be present on a dataset to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      Property equalities that must ALL match. String values match string properties;
      numeric values match numeric properties, without coercing strings to numbers.
      Integer values are converted to floats.
    - **before** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Searches for datasets ingested before some time (inclusive).
    - **after** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Searches for datasets ingested after some time (inclusive).
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter results to the given archive status.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All datasets which match all of the provided conditions

Raises:
:   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset")]

### search_events(*, search_text=None, after=None, before=None, assets=None, labels=None, properties=None, created_by=None, workbook=None, data_review=None, assignee=None, event_type=None, priority=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for events meeting the specified filters.
Filters are ANDed together, e.g. `(event.label == label) AND (event.start > before)`

Parameters:
:   - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Searches for a string in the event’s metadata.
    - **after** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Filters to end times after this time, exclusive.
    - **before** ([*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Filters to start times before this time, exclusive.
    - **assets** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      List of assets that must ALL be present on an event to be included.
    - **labels** ([*Iterable*](https://docs.python.org/3/library/typing.html#typing.Iterable "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A list of labels that must ALL be present on an event to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      Property equalities that must ALL match. String values match string properties;
      numeric values match numeric properties, without coercing strings to numbers.
      Integer values are converted to floats.
    - **created_by** ([*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      A User (or rid) of the author that must be present on an event to be included.
    - **workbook** ([*Workbook*](https://dev.nominal.io/python/ref/generated/nominal.core.Workbook.md#nominal.core.Workbook "nominal.core.workbook.Workbook") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Workbook to search for events on
    - **data_review** ([*DataReview*](https://dev.nominal.io/python/ref/generated/nominal.core.DataReview.md#nominal.core.DataReview "nominal.core.data_review.DataReview") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Search for events from the given data review
    - **assignee** ([*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Search for events with the given assignee
    - **event_type** ([*EventType*](https://dev.nominal.io/python/ref/generated/nominal.core.EventType.md#nominal.core.EventType "nominal.core._event_types.EventType") *|* *None*)

      Search for events based on level
    - **priority** ([*Priority*](https://dev.nominal.io/python/ref/generated/nominal.core.Priority.md#nominal.core.Priority "nominal.core._checklist_types.Priority") *|* *None*)

      Filter events by disposition priority. None leaves priority unrestricted.
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Event*](https://dev.nominal.io/python/ref/generated/nominal.core.Event.md#nominal.core.Event "nominal.core.event.Event")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace` (default), the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All events which match all of the provided conditions

Raises:
:   [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Event*](https://dev.nominal.io/python/ref/generated/nominal.core.Event.md#nominal.core.Event "nominal.core.event.Event")]

### search_ingestion_jobs(*, datasets=None, created_by=None, statuses=None, search_text=None, start_time_after=None, start_time_before=None, workspace=WorkspaceSearchType.DEFAULT)

Search ingest jobs. Filters are ANDed together.

Results are limited to datasets the caller can read; jobs without a persisted dataset are
never returned by search.

Parameters:
:   - **datasets** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Dataset*](https://dev.nominal.io/python/ref/generated/nominal.core.Dataset.md#nominal.core.Dataset "nominal.core.dataset.Dataset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Only jobs targeting any of these datasets (or their RIDs).
    - **created_by** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Only jobs created by any of these users or user RIDs.
    - **statuses** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*IngestionJobStatus*](https://dev.nominal.io/python/ref/generated/nominal.core.IngestionJobStatus.md#nominal.core.IngestionJobStatus "nominal.core.ingestion_job.IngestionJobStatus")*]* *|* *None*)

      Only jobs in any of these statuses.
    - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Case-insensitive substring match against origin file paths.
    - **start_time_after** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Only jobs that started at or after this time (inclusive).
    - **start_time_before** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Only jobs that started before this time (exclusive).
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*IngestionJob*](https://dev.nominal.io/python/ref/generated/nominal.core.IngestionJob.md#nominal.core.IngestionJob "nominal.core.ingestion_job.IngestionJob")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All ingest jobs matching all of the provided conditions, most recent first.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*IngestionJob*](https://dev.nominal.io/python/ref/generated/nominal.core.IngestionJob.md#nominal.core.IngestionJob "nominal.core.ingestion_job.IngestionJob")]

### search_markings(id_substring=None)

Search markings in the current organization, oldest first.

Parameters:
:   **id_substring** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

    Substring that a marking’s id must contain to be included.

Returns:
:   All markings matching the given conditions.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Marking*](https://dev.nominal.io/python/ref/generated/nominal.core.Marking.md#nominal.core.Marking "nominal.core.marking.Marking")]

> **Note**
>
> Markings are scoped to an organization rather than a workspace, so this search takes no
> workspace filter. Archived markings are never returned; fetch them by RID with
> [`get_marking`](https://dev.nominal.io/python/ref/generated/nominal.core.NominalClient.md#nominal.core.NominalClient.get_marking "nominal.core.NominalClient.get_marking") instead.

### search_runs(start=None, end=None, name_substring=None, *, asset=None, run_prefix=None, labels=None, properties=None, exact_match=None, search_text=None, created_after=None, created_before=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for runs meeting the specified filters.
Filters are ANDed together, e.g. `(run.label == label) AND (run.end <= end)`

Parameters:
:   - **start** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Inclusive start time for filtering runs.
    - **end** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Inclusive end time for filtering runs.
    - **name_substring** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Alias for `exact_match`: despite the name, this matches a case-insensitive substring
      of the run’s name, description, labels, or properties. For name-only matching, filter the
      returned runs on their names.
    - **asset** ([*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filter runs associated with this asset or asset RID.
    - **run_prefix** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filter by the stored run prefix, not a substring of the run name.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A sequence of labels that must ALL be present on a run to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*float*](https://docs.python.org/3/builtins/functions.html#float "(in Python v3.15)")*]* *|* *None*)

      Property equalities that must ALL match. String values match string properties;
      numeric values match numeric properties, without coercing strings to numbers.
      Integer values are converted to floats.
    - **exact_match** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Case-insensitive substring of the run’s name, description, labels, or properties.
    - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Fuzzy match: tokenized across name, description, labels, and properties, with additional
      substring and similarity matching on name and description, so results need not contain the given
      text verbatim.
    - **created_after** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Filter runs created after this timestamp (exclusive).
    - **created_before** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* [*datetime*](https://docs.python.org/3/library/datetime.html#datetime.datetime "(in Python v3.15)") *|* [*int*](https://docs.python.org/3/builtins/functions.html#int "(in Python v3.15)") *|* *None*)

      Filter runs created before this timestamp (exclusive).
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Run*](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run "nominal.core.run.Run")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All runs which match all of the provided conditions

Raises:
:   - [**TypeError**](https://docs.python.org/3/builtins/exceptions.html#TypeError "(in Python v3.15)") – If a property value is a boolean or is not a string, integer, or float.
    - [**NominalConfigError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalConfigError.md#nominal.exceptions.NominalConfigError "nominal.exceptions.NominalConfigError") – If the default workspace is requested but cannot be resolved.
    - [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If a search request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Run*](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run "nominal.core.run.Run")]

### search_secrets(search_text=None, labels=None, properties=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for secrets meeting the specified filters.
Filters are ANDed together, e.g. `(secret.label == label) AND (secret.property == property)`

Parameters:
:   - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Fuzzy match: tokenized across name, description, labels, and properties, with additional
      substring and similarity matching on name and description, so results need not contain the given
      text verbatim.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A sequence of labels that must ALL be present on a secret to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A mapping of key-value pairs that must ALL be present on a secret to be included.
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Secret*](https://dev.nominal.io/python/ref/generated/nominal.core.Secret.md#nominal.core.Secret "nominal.core.secret.Secret")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All secrets which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Secret*](https://dev.nominal.io/python/ref/generated/nominal.core.Secret.md#nominal.core.Secret "nominal.core.secret.Secret")]

### search_users(exact_match=None, search_text=None)

Search for users meeting the specified filters.
Filters are ANDed together, e.g., if exact_match and search_text are both provided, then both must match.

Parameters:
:   - **exact_match** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Searches for an exact (case-insensitive) substring of the user’s email
    - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Searches for a (case-insensitive) substring across display name and email

Returns:
:   All users which match all of the provided conditions

Raises:
:   [**NominalError**](https://dev.nominal.io/python/ref/generated/nominal.exceptions.NominalError.md#nominal.exceptions.NominalError "nominal.exceptions.NominalError") – If the user search request fails.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User")]

### search_videos(search_text=None, labels=None, properties=None, workspace=WorkspaceSearchType.DEFAULT, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for videos meeting the specified filters.
Filters are ANDed together, e.g. `(video.label == label) AND (video.property == property)`

Parameters:
:   - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Fuzzy match: tokenized across name, description, labels, and properties, with additional
      substring and similarity matching on name and description, so results need not contain the given
      text verbatim.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A sequence of labels that must ALL be present on a video to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A mapping of key-value pairs that must ALL be present on a video to be included.
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter by archive status. Defaults to NOT_ARCHIVED.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Video*](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video "nominal.core.video.Video")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All videos which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Video*](https://dev.nominal.io/python/ref/generated/nominal.core.Video.md#nominal.core.Video "nominal.core.video.Video")]

### search_workbook_templates(*, exact_match=None, search_text=None, labels=None, properties=None, created_by=None, archive_status=ArchiveStatusFilter.NOT_ARCHIVED, published=None, workspace=WorkspaceSearchType.DEFAULT)

Search for workbook templates meeting the specified filters.
Filters are ANDed together, e.g. `(workbook.label == label) AND (workbook.author_rid == "rid")`

Parameters:
:   - **exact_match** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Case-insensitive substring of the template’s title.
    - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Fuzzy (similarity) match against the template’s title or description.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A list of labels that must ALL be present on an workbook to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A mapping of key-value pairs that must ALL be present on an workbook to be included.
    - **created_by** ([*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Searches for workbook templates with the given creator’s rid
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Filter results to the given archive status.
    - **published** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      Searches for workbook templates that have been published if true
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*WorkbookTemplate*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkbookTemplate.md#nominal.core.WorkbookTemplate "nominal.core.workbook_template.WorkbookTemplate")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All workbook templates which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*WorkbookTemplate*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkbookTemplate.md#nominal.core.WorkbookTemplate "nominal.core.workbook_template.WorkbookTemplate")]

### search_workbooks(*, exact_match=None, search_text=None, labels=None, properties=None, asset=None, exact_assets=None, created_by=None, run=None, workspace=WorkspaceSearchType.DEFAULT, include_drafts=False, archive_status=ArchiveStatusFilter.NOT_ARCHIVED)

Search for workbooks meeting the specified filters.
Filters are ANDed together, e.g. `(workbook.label == label) AND (workbook.created_by == "rid")`

Parameters:
:   - **exact_match** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Case-insensitive substring of the workbook’s title.
    - **search_text** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Case-insensitive substring of the workbook’s title or description.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A list of labels that must ALL be present on an workbook to be included.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      A mapping of key-value pairs that must ALL be present on an workbook to be included.
    - **asset** ([*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Searches for workbooks that include the given asset
    - **exact_assets** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*Asset*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.asset.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Searches for workbooks that have the exact given assets
    - **created_by** ([*User*](https://dev.nominal.io/python/ref/generated/nominal.core.User.md#nominal.core.User "nominal.core.user.User") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Searches for workbooks with the given author
    - **run** ([*Run*](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run "nominal.core.run.Run") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Searches for workbooks with the given run
    - **workspace** ([*WorkspaceSearchType*](https://dev.nominal.io/python/ref/generated/nominal.core.WorkspaceSearchType.md#nominal.core.WorkspaceSearchType "nominal.core.client.WorkspaceSearchType") *|* [*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.workspace.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Filters search to given workspace.
    - **include_drafts** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      If true, include workbooks in draft state in results.
    - **archive_status** ([*ArchiveStatusFilter*](https://dev.nominal.io/python/ref/generated/nominal.core.ArchiveStatusFilter.md#nominal.core.ArchiveStatusFilter "nominal.core._utils.query_tools.ArchiveStatusFilter"))

      Archive status to filter results to. Defaults to NOT_ARCHIVED.

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Workbook*](https://dev.nominal.io/python/ref/generated/nominal.core.Workbook.md#nominal.core.Workbook "nominal.core.workbook.Workbook")]

> **Note**
>
> If WorkspaceSearchType.ALL is given for `workspace`, the workspace filter is omitted and the
> search spans all workspaces the user can access. If WorkspaceSearchType.DEFAULT, the client prefers its
> configured `workspace_rid` (for example from `config.yml`) and otherwise falls back to a client-side
> default-workspace lookup; if neither succeeds, a NominalConfigError is raised. If a Workspace or workspace
> RID is given, that value is used directly.

Returns:
:   All workbooks which match all of the provided conditions

Return type:
:   [*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*Workbook*](https://dev.nominal.io/python/ref/generated/nominal.core.Workbook.md#nominal.core.Workbook "nominal.core.workbook.Workbook")]