Procedure executions service (gRPC)#

Fields of ProcedureExecutionMetadata

rid string
procedure_rid string: The procedure template rid this execution is based on.
procedure_commit_id string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
created_by string
created_at string (date-time)
updated_by string
updated_at string (date-time)
started_at string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
started_by string
finished_at string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finished_by string
aborted_at string (date-time): Will be true/set if the execution is the ABORTED terminal state.
aborted_by string
failed_at string (date-time): Will be set if the execution is in the ERRORED terminal state.
failed_by string
failed_reason string
asset_rids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
is_archived boolean

Fields of ProcedureExecutionState

global_fields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

asset_rid

asset_rid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

string_value

string_value string

double_value

double_value number

boolean_value

boolean_value boolean

int_value

int_value integer (int64)

strings_value

strings_value Strings

Fields of Strings

values array of string

ingest_job_rid

ingest_job_rid string

run_rid

run_rid string

file_upload_value

file_upload_value FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload_value

multi_file_upload_value MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
template_node_id string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
template_commit_id string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

template_node_id string

Unique identifier of the template node this execution node is based on. At least 1 character.

is_outdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

not_started

not_started ExecutionStepNotStarted

in_progress

in_progress ExecutionStepInProgress

Fields of ExecutionStepInProgress

started_at string (date-time)
started_by string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skipped_at string (date-time)
skipped_by string
skip_reason string
started_at string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
started_by string
submitted_at string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submitted_by string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string
succeeded_at string (date-time)
succeeded_by string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

started_at string (date-time): Optional because a step can reach ERRORED without having been started
started_by string
submitted_at string (date-time): Optional because a step can be errored before being submitted
submitted_by string
errored_at string (date-time)
errored_by string
error string
skipped_at string (date-time): Optional because a step could be skipped but then error while running completion actions
skipped_by string
skip_reason string
succeeded_at string (date-time): Optional because a step can succeed but then error while running completion actions
succeeded_by string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, start_ingest, select_or_create_asset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

Python

import grpc
from nominal.protos.procedures.executions.v1 import procedure_executions_pb2, procedure_executions_pb2_grpc

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

request = procedure_executions_pb2.CreateProcedureExecutionRequest(
    procedure_rid="<procedure rid>",
    procedure_commit_id="<procedure commit id>",
    title="<title>",
    description="<description>",
    start_immediately=True,
)
response = procedure_executions_service.CreateProcedureExecution(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	executionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/executions/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	procedureExecutionsService := executionsv1.NewProcedureExecutionsServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &executionsv1.CreateProcedureExecutionRequest{
		ProcedureRid:      "<procedure rid>",
		ProcedureCommitId: "<procedure commit id>",
		Title:             "<title>",
		Description:       proto.String("<description>"),
		StartImmediately:  proto.Bool(true),
	}
	response, err := procedureExecutionsService.CreateProcedureExecution(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "procedure_execution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedure_rid": "<procedure rid>",
      "procedure_commit_id": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "created_by": "<created by>",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_by": "<updated by>",
      "updated_at": "2026-01-01T00:00:00Z",
      "started_at": "2026-01-01T00:00:00Z",
      "started_by": "<started by>",
      "finished_at": "2026-01-01T00:00:00Z",
      "finished_by": "<finished by>",
      "aborted_at": "2026-01-01T00:00:00Z",
      "aborted_by": "<aborted by>",
      "failed_at": "2026-01-01T00:00:00Z",
      "failed_by": "<failed by>",
      "failed_reason": "<failed reason>",
      "asset_rids": [
        "<asset rids>"
      ],
      "is_archived": true
    },
    "state": {
      "global_fields": {
        "<key>": {
          "asset_rid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "template_node_id": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "template_commit_id": "<template commit id>"
          }
        }
      },
      "section_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      },
      "step_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Get procedure execution#

gRPC /nominal.procedures.executions.v1.ProcedureExecutionsService/GetProcedureExecution

Get a procedure execution by its RID

Request: GetProcedureExecutionRequest

procedure_execution_rid string
include_display_graph boolean: If true, the display graph will be included in the response. Default is false.

Response: GetProcedureExecutionResponse

procedure_execution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedure_rid string: The procedure template rid this execution is based on.
procedure_commit_id string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
created_by string
created_at string (date-time)
updated_by string
updated_at string (date-time)
started_at string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
started_by string
finished_at string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finished_by string
aborted_at string (date-time): Will be true/set if the execution is the ABORTED terminal state.
aborted_by string
failed_at string (date-time): Will be set if the execution is in the ERRORED terminal state.
failed_by string
failed_reason string
asset_rids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
is_archived boolean

Fields of ProcedureExecutionState

global_fields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

asset_rid

asset_rid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

string_value

string_value string

double_value

double_value number

boolean_value

boolean_value boolean

int_value

int_value integer (int64)

strings_value

strings_value Strings

Fields of Strings

values array of string

ingest_job_rid

ingest_job_rid string

run_rid

run_rid string

file_upload_value

file_upload_value FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload_value

multi_file_upload_value MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
template_node_id string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
template_commit_id string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

template_node_id string

Unique identifier of the template node this execution node is based on. At least 1 character.

is_outdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

not_started

not_started ExecutionStepNotStarted

in_progress

in_progress ExecutionStepInProgress

Fields of ExecutionStepInProgress

started_at string (date-time)
started_by string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skipped_at string (date-time)
skipped_by string
skip_reason string
started_at string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
started_by string
submitted_at string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submitted_by string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string
succeeded_at string (date-time)
succeeded_by string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

started_at string (date-time): Optional because a step can reach ERRORED without having been started
started_by string
submitted_at string (date-time): Optional because a step can be errored before being submitted
submitted_by string
errored_at string (date-time)
errored_by string
error string
skipped_at string (date-time): Optional because a step could be skipped but then error while running completion actions
skipped_by string
skip_reason string
succeeded_at string (date-time): Optional because a step can succeed but then error while running completion actions
succeeded_by string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, start_ingest, select_or_create_asset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

Python

import grpc
from nominal.protos.procedures.executions.v1 import procedure_executions_pb2, procedure_executions_pb2_grpc

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

request = procedure_executions_pb2.GetProcedureExecutionRequest(
    procedure_execution_rid="<procedure execution rid>",
    include_display_graph=True,
)
response = procedure_executions_service.GetProcedureExecution(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	executionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/executions/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	procedureExecutionsService := executionsv1.NewProcedureExecutionsServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &executionsv1.GetProcedureExecutionRequest{
		ProcedureExecutionRid: "<procedure execution rid>",
		IncludeDisplayGraph:   true,
	}
	response, err := procedureExecutionsService.GetProcedureExecution(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "procedure_execution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedure_rid": "<procedure rid>",
      "procedure_commit_id": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "created_by": "<created by>",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_by": "<updated by>",
      "updated_at": "2026-01-01T00:00:00Z",
      "started_at": "2026-01-01T00:00:00Z",
      "started_by": "<started by>",
      "finished_at": "2026-01-01T00:00:00Z",
      "finished_by": "<finished by>",
      "aborted_at": "2026-01-01T00:00:00Z",
      "aborted_by": "<aborted by>",
      "failed_at": "2026-01-01T00:00:00Z",
      "failed_by": "<failed by>",
      "failed_reason": "<failed reason>",
      "asset_rids": [
        "<asset rids>"
      ],
      "is_archived": true
    },
    "state": {
      "global_fields": {
        "<key>": {
          "asset_rid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "template_node_id": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "template_commit_id": "<template commit id>"
          }
        }
      },
      "section_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      },
      "step_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      }
    }
  },
  "display_graph": {
    "top_level_nodes": [
      "<top level nodes>"
    ],
    "section_to_sorted_children": {
      "<key>": {
        "node_ids": [
          "<node ids>"
        ]
      }
    }
  }
}

Repeat step#

gRPC /nominal.procedures.executions.v1.ProcedureExecutionsService/RepeatStep

Repeat a previously finished step in a procedure execution. This can only be done if the given step is in state SUCCEEDED, SKIPPED or ERRORED. Other state transitions are managed by the backend.

Request: RepeatStepRequest

procedure_execution_rid string

step_id string

The unique identifier of the execution step to repeat/duplicate. At least 1 character.

behavior RepeatStepBehavior

Behavior for how repeating the step will affect dependants.

Values of RepeatStepBehavior

REPEAT_STEP_BEHAVIOR_UNSPECIFIED
REPEAT_STEP_BEHAVIOR_ISOLATED: The targeted step will be repeated, but the original graph will be preserved and only direct children will be checked for state updates

value StepContentValue

Setting the value of the step’s content.

Fields of StepContentValue

one of form, start_ingest, select_or_create_asset, wait required

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields required

asset

asset AssetFieldValue

Fields of AssetFieldValue

asset_reference AssetReference

Fields of AssetReference

one of rid, field_id required

rid

rid string: a constant AssetRid

field_id

field_id string: The field reference that will contain an AssetRid value. The execution will fail if the field is not set but the value is accessed.

checkbox

checkbox CheckboxFieldValue

Fields of CheckboxFieldValue

value boolean: Default to false if not set

text

text TextFieldValue

Fields of TextFieldValue

value string: Default to empty string if not set

int

int IntFieldValue

Fields of IntFieldValue

value integer (int64)

double

double DoubleFieldValue

Fields of DoubleFieldValue

value number

single_enum

single_enum SingleEnumFieldValue

Fields of SingleEnumFieldValue

value string: Default to empty string if not set

multi_enum

multi_enum MultiEnumFieldValue

Fields of MultiEnumFieldValue

value array of string: Default to empty list if not set

file_upload

file_upload FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload

multi_file_upload MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

start_ingest

start_ingest StartIngestStepValue

Fields of StartIngestStepValue

ingest_job_rid string: The RID of the ingest job that was started by the client. This must be populated for the step to be submitted.

select_or_create_asset

select_or_create_asset SelectOrCreateAssetStepValue

Fields of SelectOrCreateAssetStepValue

asset_reference AssetReference: The asset that was selected / created by the client. This must be populated for the step to be submitted.

wait

wait WaitStepValue: …

auto_proceed_config AutoProceedConfig

Set whether the step has auto-proceed enabled.

Fields of AutoProceedConfig

one of disabled, enabled required

disabled

disabled Disabled: The step will not be automatically completed

enabled

enabled Enabled: The step will automatically submit the step contents once the requirements are met and begin the transition to either PASSED or ERRORED.

target_state TargetStepStateRequest

Setting the state of the step. This will occur after the other updates in this request.

Fields of TargetStepStateRequest

one of in_progress, submitted, skipped, errored required

in_progress

in_progress StepInProgressRequest

submitted

submitted StepSubmittedRequest

skipped

skipped StepSkippedRequest

Fields of StepSkippedRequest

skip_reason string

errored

errored StepErroredRequest

Fields of StepErroredRequest

error_reason string

Response: RepeatStepResponse

procedure_execution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedure_rid string: The procedure template rid this execution is based on.
procedure_commit_id string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
created_by string
created_at string (date-time)
updated_by string
updated_at string (date-time)
started_at string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
started_by string
finished_at string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finished_by string
aborted_at string (date-time): Will be true/set if the execution is the ABORTED terminal state.
aborted_by string
failed_at string (date-time): Will be set if the execution is in the ERRORED terminal state.
failed_by string
failed_reason string
asset_rids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
is_archived boolean

Fields of ProcedureExecutionState

global_fields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

asset_rid

asset_rid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

string_value

string_value string

double_value

double_value number

boolean_value

boolean_value boolean

int_value

int_value integer (int64)

strings_value

strings_value Strings

Fields of Strings

values array of string

ingest_job_rid

ingest_job_rid string

run_rid

run_rid string

file_upload_value

file_upload_value FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload_value

multi_file_upload_value MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
template_node_id string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
template_commit_id string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

template_node_id string

Unique identifier of the template node this execution node is based on. At least 1 character.

is_outdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

not_started

not_started ExecutionStepNotStarted

in_progress

in_progress ExecutionStepInProgress

Fields of ExecutionStepInProgress

started_at string (date-time)
started_by string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skipped_at string (date-time)
skipped_by string
skip_reason string
started_at string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
started_by string
submitted_at string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submitted_by string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string
succeeded_at string (date-time)
succeeded_by string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

started_at string (date-time): Optional because a step can reach ERRORED without having been started
started_by string
submitted_at string (date-time): Optional because a step can be errored before being submitted
submitted_by string
errored_at string (date-time)
errored_by string
error string
skipped_at string (date-time): Optional because a step could be skipped but then error while running completion actions
skipped_by string
skip_reason string
succeeded_at string (date-time): Optional because a step can succeed but then error while running completion actions
succeeded_by string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, start_ingest, select_or_create_asset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

Python

import grpc
from nominal.protos.procedures.executions.v1 import procedure_executions_pb2, procedure_executions_pb2_grpc

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

request = procedure_executions_pb2.RepeatStepRequest(
    procedure_execution_rid="<procedure execution rid>",
    step_id="<step id>",
    behavior="REPEAT_STEP_BEHAVIOR_ISOLATED",
    value={"form": {"fields": [{"asset": {"asset_reference": {"rid": "<rid>"}}}]}},
    auto_proceed_config={"disabled": {}},
    target_state={"in_progress": {}},
)
response = procedure_executions_service.RepeatStep(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	executionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/executions/v1"
	proceduresv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	procedureExecutionsService := executionsv1.NewProcedureExecutionsServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &executionsv1.RepeatStepRequest{
		ProcedureExecutionRid: "<procedure execution rid>",
		StepId:                "<step id>",
		Behavior:              executionsv1.RepeatStepBehavior_REPEAT_STEP_BEHAVIOR_ISOLATED,
		Value: &executionsv1.StepContentValue{
			Value: &executionsv1.StepContentValue_Form{Form: &executionsv1.FormStepValue{
				Fields: []*executionsv1.FormFieldValue{
					{
						Field: &executionsv1.FormFieldValue_Asset{Asset: &executionsv1.AssetFieldValue{
							Asset: &executionsv1.AssetFieldValue_AssetReference{AssetReference: &proceduresv1.AssetReference{
								Option: &proceduresv1.AssetReference_Rid{Rid: "<rid>"},
							}},
						}},
					},
				},
			}},
		},
		AutoProceedConfig: &proceduresv1.AutoProceedConfig{
			Config: &proceduresv1.AutoProceedConfig_Disabled_{Disabled: &proceduresv1.AutoProceedConfig_Disabled{}},
		},
		TargetState: &executionsv1.TargetStepStateRequest{
			TargetState: &executionsv1.TargetStepStateRequest_InProgress{InProgress: &executionsv1.StepInProgressRequest{}},
		},
	}
	response, err := procedureExecutionsService.RepeatStep(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "procedure_execution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedure_rid": "<procedure rid>",
      "procedure_commit_id": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "created_by": "<created by>",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_by": "<updated by>",
      "updated_at": "2026-01-01T00:00:00Z",
      "started_at": "2026-01-01T00:00:00Z",
      "started_by": "<started by>",
      "finished_at": "2026-01-01T00:00:00Z",
      "finished_by": "<finished by>",
      "aborted_at": "2026-01-01T00:00:00Z",
      "aborted_by": "<aborted by>",
      "failed_at": "2026-01-01T00:00:00Z",
      "failed_by": "<failed by>",
      "failed_reason": "<failed reason>",
      "asset_rids": [
        "<asset rids>"
      ],
      "is_archived": true
    },
    "state": {
      "global_fields": {
        "<key>": {
          "asset_rid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "template_node_id": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "template_commit_id": "<template commit id>"
          }
        }
      },
      "section_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      },
      "step_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Search procedure executions#

gRPC /nominal.procedures.executions.v1.ProcedureExecutionsService/SearchProcedureExecutions

Search for procedure executions. The JSON transcoder ranks literal path segments above /{...} template captures, so the literal /search route wins over the /{procedure_execution_rid} template regardless of declaration order.

Request: SearchProcedureExecutionsRequest

query ProcedureExecutionSearchQuery

Fields of ProcedureExecutionSearchQuery

one of 12 fields required

search_text

search_text string

label

label string

property

property Property

Fields of Property

name string
value string

and

and ProcedureExecutionSearchAndQuery

Fields of ProcedureExecutionSearchAndQuery

queries array of ProcedureExecutionSearchQuery

or ProcedureExecutionSearchOrQuery

Fields of ProcedureExecutionSearchOrQuery

queries array of ProcedureExecutionSearchQuery

workspace

workspace string

procedure_rid

procedure_rid string

commit_id

commit_id string

created_by

created_by string

progress_status

progress_status ProcedureExecutionProgressStatus

Values of ProcedureExecutionProgressStatus

PROCEDURE_EXECUTION_PROGRESS_STATUS_UNSPECIFIED
PROCEDURE_EXECUTION_PROGRESS_STATUS_NOT_STARTED
PROCEDURE_EXECUTION_PROGRESS_STATUS_IN_PROGRESS
PROCEDURE_EXECUTION_PROGRESS_STATUS_FINISHED
PROCEDURE_EXECUTION_PROGRESS_STATUS_ABORTED

assets_filter

assets_filter AssetsFilter

Fields of AssetsFilter

asset_rids array of string

operator Operator

Values of Operator

OPERATOR_UNSPECIFIED
OPERATOR_OR
OPERATOR_AND

is_archived

is_archived boolean

sort_options ProcedureExecutionSortOptions

Fields of ProcedureExecutionSortOptions

is_descending boolean

Defaults to descending

sort_field SearchProcedureExecutionsSortField required

Values of SearchProcedureExecutionsSortField

SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_UNSPECIFIED
SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT
SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_STARTED_AT
SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_FINISHED_AT
SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_UPDATED_AT

page_size integer

Page sizes greater than 1_000 will be rejected. Default pageSize is 100. From 1 to 1,000.

next_page_token string

Response: SearchProcedureExecutionsResponse

procedure_executions array of ProcedureExecutionMetadata

Fields of ProcedureExecutionMetadata

rid string
procedure_rid string: The procedure template rid this execution is based on.
procedure_commit_id string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
created_by string
created_at string (date-time)
updated_by string
updated_at string (date-time)
started_at string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
started_by string
finished_at string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finished_by string
aborted_at string (date-time): Will be true/set if the execution is the ABORTED terminal state.
aborted_by string
failed_at string (date-time): Will be set if the execution is in the ERRORED terminal state.
failed_by string
failed_reason string
asset_rids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
is_archived boolean

next_page_token string

Request

Python

import grpc
from nominal.protos.procedures.executions.v1 import procedure_executions_pb2, procedure_executions_pb2_grpc

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

request = procedure_executions_pb2.SearchProcedureExecutionsRequest(
    query={"search_text": "<search text>"},
    sort_options={"sort_field": "SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT"},
    page_size=1,
    next_page_token="<next page token>",
)
response = procedure_executions_service.SearchProcedureExecutions(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	executionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/executions/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	procedureExecutionsService := executionsv1.NewProcedureExecutionsServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &executionsv1.SearchProcedureExecutionsRequest{
		Query: &executionsv1.ProcedureExecutionSearchQuery{
			Query: &executionsv1.ProcedureExecutionSearchQuery_SearchText{SearchText: "<search text>"},
		},
		SortOptions: &executionsv1.ProcedureExecutionSortOptions{
			SortField: executionsv1.SearchProcedureExecutionsSortField_SEARCH_PROCEDURE_EXECUTIONS_SORT_FIELD_CREATED_AT,
		},
		PageSize:      proto.Int32(1),
		NextPageToken: proto.String("<next page token>"),
	}
	response, err := procedureExecutionsService.SearchProcedureExecutions(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "procedure_executions": [
    {
      "rid": "<rid>",
      "procedure_rid": "<procedure rid>",
      "procedure_commit_id": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "created_by": "<created by>",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_by": "<updated by>",
      "updated_at": "2026-01-01T00:00:00Z",
      "started_at": "2026-01-01T00:00:00Z",
      "started_by": "<started by>",
      "finished_at": "2026-01-01T00:00:00Z",
      "finished_by": "<finished by>",
      "aborted_at": "2026-01-01T00:00:00Z",
      "aborted_by": "<aborted by>",
      "failed_at": "2026-01-01T00:00:00Z",
      "failed_by": "<failed by>",
      "failed_reason": "<failed reason>",
      "asset_rids": [
        "<asset rids>"
      ],
      "is_archived": true
    }
  ],
  "next_page_token": "<next page token>"
}

Update procedure execution#

gRPC /nominal.procedures.executions.v1.ProcedureExecutionsService/UpdateProcedureExecution

Heavy-handed update method for procedure execution.

Request: UpdateProcedureExecutionRequest

procedure_execution_rid string

title string

description string

commit_id string

labels LabelUpdateWrapper

Fields of LabelUpdateWrapper

labels array of string

properties PropertyUpdateWrapper

Fields of PropertyUpdateWrapper

properties map of string to string

Fields of ProcedureExecutionState

global_fields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

asset_rid

asset_rid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

string_value

string_value string

double_value

double_value number

boolean_value

boolean_value boolean

int_value

int_value integer (int64)

strings_value

strings_value Strings

Fields of Strings

values array of string

ingest_job_rid

ingest_job_rid string

run_rid

run_rid string

file_upload_value

file_upload_value FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload_value

multi_file_upload_value MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step required

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
template_node_id string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
template_commit_id string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

template_node_id string

Unique identifier of the template node this execution node is based on. At least 1 character.

is_outdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields required

not_started

not_started ExecutionStepNotStarted

in_progress

in_progress ExecutionStepInProgress

Fields of ExecutionStepInProgress

started_at string (date-time)
started_by string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skipped_at string (date-time)
skipped_by string
skip_reason string
started_at string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
started_by string
submitted_at string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submitted_by string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string
succeeded_at string (date-time)
succeeded_by string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

started_at string (date-time): Optional because a step can reach ERRORED without having been started
started_by string
submitted_at string (date-time): Optional because a step can be errored before being submitted
submitted_by string
errored_at string (date-time)
errored_by string
error string
skipped_at string (date-time): Optional because a step could be skipped but then error while running completion actions
skipped_by string
skip_reason string
succeeded_at string (date-time): Optional because a step can succeed but then error while running completion actions
succeeded_by string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, start_ingest, select_or_create_asset, wait required

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields required

asset

asset AssetFieldValue

Request

Python

from datetime import datetime, timezone

import grpc
from nominal.protos.procedures.executions.v1 import procedure_executions_pb2, procedure_executions_pb2_grpc

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

request = procedure_executions_pb2.UpdateProcedureExecutionRequest(
    procedure_execution_rid="<procedure execution rid>",
    title="<title>",
    description="<description>",
    commit_id="<commit id>",
    labels={"labels": ["<labels>"]},
    properties={"properties": {"<key>": "<value>"}},
    state={
        "global_fields": {"<key>": {"asset_rid": "<asset rid>"}},
        "nodes": {
            "<key>": {
                "section": {
                    "id": "<id>",
                    "template_node_id": "<template node id>",
                    "title": "<title>",
                    "description": "<description>",
                    "template_commit_id": "<template commit id>",
                },
            },
        },
        "section_edges": {"<key>": {"node_ids": ["<node ids>"]}},
        "step_edges": {"<key>": {"node_ids": ["<node ids>"]}},
    },
    is_aborted=True,
    started_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
    finished_at=datetime(2026, 1, 1, tzinfo=timezone.utc),
)
response = procedure_executions_service.UpdateProcedureExecution(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"
	"time"

	executionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/executions/v1"
	proceduresv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/v1"
	"github.com/nominal-io/nominal-api-protos-go/nominal/protos/types"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
	"google.golang.org/protobuf/types/known/timestamppb"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	procedureExecutionsService := executionsv1.NewProcedureExecutionsServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &executionsv1.UpdateProcedureExecutionRequest{
		ProcedureExecutionRid: "<procedure execution rid>",
		Title:                 proto.String("<title>"),
		Description:           proto.String("<description>"),
		CommitId:              proto.String("<commit id>"),
		Labels: &types.LabelUpdateWrapper{
			Labels: []string{
				"<labels>",
			},
		},
		Properties: &types.PropertyUpdateWrapper{
			Properties: map[string]string{
				"<key>": "<value>",
			},
		},
		State: &executionsv1.ProcedureExecutionState{
			GlobalFields: map[string]*executionsv1.FieldOutput{
				"<key>": {
					Output: &executionsv1.FieldOutput_AssetRid{AssetRid: "<asset rid>"},
				},
			},
			Nodes: map[string]*executionsv1.ProcedureExecutionNode{
				"<key>": {
					Node: &executionsv1.ProcedureExecutionNode_Section{Section: &executionsv1.ProcedureExecutionSectionNode{
						Id:               "<id>",
						TemplateNodeId:   "<template node id>",
						Title:            "<title>",
						Description:      proto.String("<description>"),
						TemplateCommitId: proto.String("<template commit id>"),
					}},
				},
			},
			SectionEdges: map[string]*proceduresv1.NodeList{
				"<key>": {
					NodeIds: []string{
						"<node ids>",
					},
				},
			},
			StepEdges: map[string]*proceduresv1.NodeList{
				"<key>": {
					NodeIds: []string{
						"<node ids>",
					},
				},
			},
		},
		IsAborted:  proto.Bool(true),
		StartedAt:  timestamppb.New(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)),
		FinishedAt: timestamppb.New(time.Date(2026, 1, 1, 0, 0, 0, 0, time.UTC)),
	}
	response, err := procedureExecutionsService.UpdateProcedureExecution(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "procedure_execution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedure_rid": "<procedure rid>",
      "procedure_commit_id": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "created_by": "<created by>",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_by": "<updated by>",
      "updated_at": "2026-01-01T00:00:00Z",
      "started_at": "2026-01-01T00:00:00Z",
      "started_by": "<started by>",
      "finished_at": "2026-01-01T00:00:00Z",
      "finished_by": "<finished by>",
      "aborted_at": "2026-01-01T00:00:00Z",
      "aborted_by": "<aborted by>",
      "failed_at": "2026-01-01T00:00:00Z",
      "failed_by": "<failed by>",
      "failed_reason": "<failed reason>",
      "asset_rids": [
        "<asset rids>"
      ],
      "is_archived": true
    },
    "state": {
      "global_fields": {
        "<key>": {
          "asset_rid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "template_node_id": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "template_commit_id": "<template commit id>"
          }
        }
      },
      "section_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      },
      "step_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Update procedure execution metadata#

gRPC /nominal.procedures.executions.v1.ProcedureExecutionsService/UpdateProcedureExecutionMetadata

Update the metadata of a procedure execution

Request: UpdateProcedureExecutionMetadataRequest

procedure_execution_rid string

title string

description string

commit_id string

labels LabelUpdateWrapper

Fields of LabelUpdateWrapper

labels array of string

properties PropertyUpdateWrapper

Fields of PropertyUpdateWrapper

properties map of string to string

Response: UpdateProcedureExecutionMetadataResponse

Fields of ProcedureExecutionMetadata

rid string
procedure_rid string: The procedure template rid this execution is based on.
procedure_commit_id string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
created_by string
created_at string (date-time)
updated_by string
updated_at string (date-time)
started_at string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
started_by string
finished_at string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finished_by string
aborted_at string (date-time): Will be true/set if the execution is the ABORTED terminal state.
aborted_by string
failed_at string (date-time): Will be set if the execution is in the ERRORED terminal state.
failed_by string
failed_reason string
asset_rids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
is_archived boolean

Request

Python

import grpc
from nominal.protos.procedures.executions.v1 import procedure_executions_pb2, procedure_executions_pb2_grpc

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

request = procedure_executions_pb2.UpdateProcedureExecutionMetadataRequest(
    procedure_execution_rid="<procedure execution rid>",
    title="<title>",
    description="<description>",
    commit_id="<commit id>",
    labels={"labels": ["<labels>"]},
    properties={"properties": {"<key>": "<value>"}},
)
response = procedure_executions_service.UpdateProcedureExecutionMetadata(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	executionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/executions/v1"
	"github.com/nominal-io/nominal-api-protos-go/nominal/protos/types"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
	"google.golang.org/protobuf/proto"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	procedureExecutionsService := executionsv1.NewProcedureExecutionsServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &executionsv1.UpdateProcedureExecutionMetadataRequest{
		ProcedureExecutionRid: "<procedure execution rid>",
		Title:                 proto.String("<title>"),
		Description:           proto.String("<description>"),
		CommitId:              proto.String("<commit id>"),
		Labels: &types.LabelUpdateWrapper{
			Labels: []string{
				"<labels>",
			},
		},
		Properties: &types.PropertyUpdateWrapper{
			Properties: map[string]string{
				"<key>": "<value>",
			},
		},
	}
	response, err := procedureExecutionsService.UpdateProcedureExecutionMetadata(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "metadata": {
    "rid": "<rid>",
    "procedure_rid": "<procedure rid>",
    "procedure_commit_id": "<procedure commit id>",
    "title": "<title>",
    "description": "<description>",
    "labels": [
      "<labels>"
    ],
    "properties": {
      "<key>": "<value>"
    },
    "created_by": "<created by>",
    "created_at": "2026-01-01T00:00:00Z",
    "updated_by": "<updated by>",
    "updated_at": "2026-01-01T00:00:00Z",
    "started_at": "2026-01-01T00:00:00Z",
    "started_by": "<started by>",
    "finished_at": "2026-01-01T00:00:00Z",
    "finished_by": "<finished by>",
    "aborted_at": "2026-01-01T00:00:00Z",
    "aborted_by": "<aborted by>",
    "failed_at": "2026-01-01T00:00:00Z",
    "failed_by": "<failed by>",
    "failed_reason": "<failed reason>",
    "asset_rids": [
      "<asset rids>"
    ],
    "is_archived": true
  }
}

Update step#

gRPC /nominal.procedures.executions.v1.ProcedureExecutionsService/UpdateStep

Update the status of a step in a procedure execution. This can only be done if the step is NOT_STARTED, IN_PROGRESS, or SUBMITTED. Other state transitions are managed by the backend.

Request: UpdateStepRequest

procedure_execution_rid string

step_id string

The unique identifier of the execution step to update. At least 1 character.

value StepContentValue

Setting the value of the step’s content. This is only allowed if the step is NOT_STARTED or IN_PROGRESS.

Fields of StepContentValue

one of form, start_ingest, select_or_create_asset, wait required

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields required

asset

asset AssetFieldValue

Fields of AssetFieldValue

asset_reference AssetReference

Fields of AssetReference

one of rid, field_id required

rid

rid string: a constant AssetRid

field_id

field_id string: The field reference that will contain an AssetRid value. The execution will fail if the field is not set but the value is accessed.

checkbox

checkbox CheckboxFieldValue

Fields of CheckboxFieldValue

value boolean: Default to false if not set

text

text TextFieldValue

Fields of TextFieldValue

value string: Default to empty string if not set

int

int IntFieldValue

Fields of IntFieldValue

value integer (int64)

double

double DoubleFieldValue

Fields of DoubleFieldValue

value number

single_enum

single_enum SingleEnumFieldValue

Fields of SingleEnumFieldValue

value string: Default to empty string if not set

multi_enum

multi_enum MultiEnumFieldValue

Fields of MultiEnumFieldValue

value array of string: Default to empty list if not set

file_upload

file_upload FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload

multi_file_upload MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

start_ingest

start_ingest StartIngestStepValue

Fields of StartIngestStepValue

ingest_job_rid string: The RID of the ingest job that was started by the client. This must be populated for the step to be submitted.

select_or_create_asset

select_or_create_asset SelectOrCreateAssetStepValue

Fields of SelectOrCreateAssetStepValue

asset_reference AssetReference: The asset that was selected / created by the client. This must be populated for the step to be submitted.

wait

wait WaitStepValue: …

auto_proceed_config AutoProceedConfig

Set whether the step has auto-proceed enabled. This is only allowed if the step is NOT_STARTED. or IN_PROGRESS.

Fields of AutoProceedConfig

one of disabled, enabled required

disabled

disabled Disabled: The step will not be automatically completed

enabled

enabled Enabled: The step will automatically submit the step contents once the requirements are met and begin the transition to either PASSED or ERRORED.

target_state TargetStepStateRequest

Setting the state of the step. This will occur after the other updates in this request.

Fields of TargetStepStateRequest

one of in_progress, submitted, skipped, errored required

in_progress

in_progress StepInProgressRequest

submitted

submitted StepSubmittedRequest

skipped

skipped StepSkippedRequest

Fields of StepSkippedRequest

skip_reason string

errored

errored StepErroredRequest

Fields of StepErroredRequest

error_reason string

Response: UpdateStepResponse

procedure_execution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedure_rid string: The procedure template rid this execution is based on.
procedure_commit_id string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
created_by string
created_at string (date-time)
updated_by string
updated_at string (date-time)
started_at string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
started_by string
finished_at string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finished_by string
aborted_at string (date-time): Will be true/set if the execution is the ABORTED terminal state.
aborted_by string
failed_at string (date-time): Will be set if the execution is in the ERRORED terminal state.
failed_by string
failed_reason string
asset_rids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
is_archived boolean

Fields of ProcedureExecutionState

global_fields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

asset_rid

asset_rid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

string_value

string_value string

double_value

double_value number

boolean_value

boolean_value boolean

int_value

int_value integer (int64)

strings_value

strings_value Strings

Fields of Strings

values array of string

ingest_job_rid

ingest_job_rid string

run_rid

run_rid string

file_upload_value

file_upload_value FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload_value

multi_file_upload_value MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
template_node_id string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
template_commit_id string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

template_node_id string

Unique identifier of the template node this execution node is based on. At least 1 character.

is_outdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.

The current status of the step along with metadata about the status transitions.

Fields of ExecutionStepState

one of 6 fields

not_started

not_started ExecutionStepNotStarted

in_progress

in_progress ExecutionStepInProgress

Fields of ExecutionStepInProgress

started_at string (date-time)
started_by string

submitted

submitted ExecutionStepSubmitted

Fields of ExecutionStepSubmitted

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string

skipped

skipped ExecutionStepSkipped

Terminal states below

Fields of ExecutionStepSkipped

skipped_at string (date-time)
skipped_by string
skip_reason string
started_at string (date-time): Optional because a step can be skipped from the NOT_STARTED state before these are set
started_by string
submitted_at string (date-time): Optional because a step can be skipped from the IN_PROGRESS state before these are set
submitted_by string

succeeded

succeeded ExecutionStepSucceeded

Fields of ExecutionStepSucceeded

started_at string (date-time)
started_by string
submitted_at string (date-time)
submitted_by string
succeeded_at string (date-time)
succeeded_by string

errored

errored ExecutionStepErrored

Fields of ExecutionStepErrored

started_at string (date-time): Optional because a step can reach ERRORED without having been started
started_by string
submitted_at string (date-time): Optional because a step can be errored before being submitted
submitted_by string
errored_at string (date-time)
errored_by string
error string
skipped_at string (date-time): Optional because a step could be skipped but then error while running completion actions
skipped_by string
skip_reason string
succeeded_at string (date-time): Optional because a step can succeed but then error while running completion actions
succeeded_by string

value StepContentValue

The current value for the content of the step.

Fields of StepContentValue

one of form, start_ingest, select_or_create_asset, wait

form

form FormStepValue

Fields of FormStepValue

fields array of FormFieldValue

Fields of FormFieldValue

one of 9 fields

Request

Python

import grpc
from nominal.protos.procedures.executions.v1 import procedure_executions_pb2, procedure_executions_pb2_grpc

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

request = procedure_executions_pb2.UpdateStepRequest(
    procedure_execution_rid="<procedure execution rid>",
    step_id="<step id>",
    value={"form": {"fields": [{"asset": {"asset_reference": {"rid": "<rid>"}}}]}},
    auto_proceed_config={"disabled": {}},
    target_state={"in_progress": {}},
)
response = procedure_executions_service.UpdateStep(request, metadata=auth)
print(response)

package main

import (
	"context"
	"crypto/tls"
	"fmt"
	"log"

	executionsv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/executions/v1"
	proceduresv1 "github.com/nominal-io/nominal-api-protos-go/nominal/protos/procedures/v1"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/metadata"
)

func main() {
	conn, err := grpc.NewClient("api.gov.nominal.io:443",
		grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{})))
	if err != nil {
		log.Fatal(err)
	}
	defer conn.Close()
	procedureExecutionsService := executionsv1.NewProcedureExecutionsServiceClient(conn)
	ctx := metadata.AppendToOutgoingContext(context.Background(), "authorization", "Bearer <api key>")

	request := &executionsv1.UpdateStepRequest{
		ProcedureExecutionRid: "<procedure execution rid>",
		StepId:                "<step id>",
		Value: &executionsv1.StepContentValue{
			Value: &executionsv1.StepContentValue_Form{Form: &executionsv1.FormStepValue{
				Fields: []*executionsv1.FormFieldValue{
					{
						Field: &executionsv1.FormFieldValue_Asset{Asset: &executionsv1.AssetFieldValue{
							Asset: &executionsv1.AssetFieldValue_AssetReference{AssetReference: &proceduresv1.AssetReference{
								Option: &proceduresv1.AssetReference_Rid{Rid: "<rid>"},
							}},
						}},
					},
				},
			}},
		},
		AutoProceedConfig: &proceduresv1.AutoProceedConfig{
			Config: &proceduresv1.AutoProceedConfig_Disabled_{Disabled: &proceduresv1.AutoProceedConfig_Disabled{}},
		},
		TargetState: &executionsv1.TargetStepStateRequest{
			TargetState: &executionsv1.TargetStepStateRequest_InProgress{InProgress: &executionsv1.StepInProgressRequest{}},
		},
	}
	response, err := procedureExecutionsService.UpdateStep(ctx, request)
	if err != nil {
		log.Fatal(err)
	}
	fmt.Println(response)
}

Response

{
  "procedure_execution": {
    "rid": "<rid>",
    "metadata": {
      "rid": "<rid>",
      "procedure_rid": "<procedure rid>",
      "procedure_commit_id": "<procedure commit id>",
      "title": "<title>",
      "description": "<description>",
      "labels": [
        "<labels>"
      ],
      "properties": {
        "<key>": "<value>"
      },
      "created_by": "<created by>",
      "created_at": "2026-01-01T00:00:00Z",
      "updated_by": "<updated by>",
      "updated_at": "2026-01-01T00:00:00Z",
      "started_at": "2026-01-01T00:00:00Z",
      "started_by": "<started by>",
      "finished_at": "2026-01-01T00:00:00Z",
      "finished_by": "<finished by>",
      "aborted_at": "2026-01-01T00:00:00Z",
      "aborted_by": "<aborted by>",
      "failed_at": "2026-01-01T00:00:00Z",
      "failed_by": "<failed by>",
      "failed_reason": "<failed reason>",
      "asset_rids": [
        "<asset rids>"
      ],
      "is_archived": true
    },
    "state": {
      "global_fields": {
        "<key>": {
          "asset_rid": "<asset rid>"
        }
      },
      "nodes": {
        "<key>": {
          "section": {
            "id": "<id>",
            "template_node_id": "<template node id>",
            "title": "<title>",
            "description": "<description>",
            "template_commit_id": "<template commit id>"
          }
        }
      },
      "section_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      },
      "step_edges": {
        "<key>": {
          "node_ids": [
            "<node ids>"
          ]
        }
      }
    }
  }
}

Update step channel capture status#

gRPC /nominal.procedures.executions.v1.ProcedureExecutionsService/UpdateStepChannelCaptureStatus

Called by the backend (channel capture executor) to merge a single channel-capture status into a step’s channel_capture_statuses. Identity is (output_field_id, capture_moment); existing entries for that identity are replaced. Statuses are written incrementally as captures progress (in_progress -> terminal), so this RPC is expected to be called multiple times per capture.

Request: UpdateStepChannelCaptureStatusRequest

procedure_execution_rid string

step_id string

The unique identifier of the execution step to update. At least 1 character.

channel_capture_status ChannelCaptureStatus

The status to merge into the step’s channel_capture_statuses, identified by (output_field_id, capture_moment). Replaces any previously written entry with the same identity.

Fields of ChannelCaptureStatus

output_field_id string

The output_field_id of the capture. Used together with capture_moment to identify which capture this status refers to. At least 1 character.

capture_moment CaptureMoment

Which step lifecycle moment this capture corresponds to. A given output_field_id may be captured at both step start and step completion, in which case there will be one ChannelCaptureStatus entry per moment. Must be a defined, non-UNSPECIFIED CaptureMoment — capture_moment is half of the identity key used for merging, so accepting the zero value would produce a bogus key.

Values of CaptureMoment

CAPTURE_MOMENT_UNSPECIFIED: Required zero-value enum sentinel. Do not include this in capture_moments.
CAPTURE_MOMENT_STEP_START
CAPTURE_MOMENT_STEP_COMPLETION

one of in_progress, succeeded, failed, skipped required

in_progress

in_progress ChannelCaptureInProgress

Fields of ChannelCaptureInProgress

started_at string (date-time)

succeeded

succeeded ChannelCaptureSucceeded

Fields of ChannelCaptureSucceeded

started_at string (date-time)

captured_at string (date-time)

value CapturedValue required

Fields of CapturedValue

one of double_value, int_value, bool_value, string_value required

double_value

double_value number

int_value

int_value integer (int64)

bool_value

bool_value boolean

string_value

string_value string

failed

failed ChannelCaptureFailed

Fields of ChannelCaptureFailed

started_at string (date-time)

failed_at string (date-time)

reason ChannelCaptureFailureReason

Values of ChannelCaptureFailureReason

CHANNEL_CAPTURE_FAILURE_REASON_UNSPECIFIED
CHANNEL_CAPTURE_FAILURE_REASON_DATA_SOURCE_NOT_FOUND: The channel’s data_source_ref could not be resolved to a concrete data source at execution time (e.g. the named ref is not present in the execution’s data scopes or run data sources).
CHANNEL_CAPTURE_FAILURE_REASON_CHANNEL_NOT_FOUND: The data source was resolved but the named channel (with the configured tags, if any) does not exist on it, or its metadata could not be fetched.
CHANNEL_CAPTURE_FAILURE_REASON_UNSUPPORTED_CHANNEL_TYPE: The channel’s data type cannot be represented by CapturedValue, or the channel’s data type is unset. Permanent for this channel — re-running will not help.
CHANNEL_CAPTURE_FAILURE_REASON_TIMEOUT_NO_DATA: No data point arrived within the capture timeout window (subscription opened but yielded no value before the deadline).
CHANNEL_CAPTURE_FAILURE_REASON_INTERNAL_ERROR: Catch-all for backend / infrastructure failures that prevented capture — e.g. websocket connect/subscribe/stream failure, missing websocket configuration, downstream event creation failure, interrupt, or any other unexpected failure. See error_message for the specific cause.

error_message string

Free-text detail. Must not contain unsafe content — same conventions as other user-visible error_message fields on procedure executions. Capped to bound payload size; truncate at the producer if a longer detail is available. At most 4,096 characters.

skipped

skipped ChannelCaptureSkipped

Fields of ChannelCaptureSkipped

skipped_at string (date-time)

reason ChannelCaptureSkipReason

Values of ChannelCaptureSkipReason

CHANNEL_CAPTURE_SKIP_REASON_UNSPECIFIED
CHANNEL_CAPTURE_SKIP_REASON_RUN_SCOPED_UNSUPPORTED: The capture targets a run-scoped channel locator, which is not yet supported.

Response: UpdateStepChannelCaptureStatusResponse

procedure_execution ProcedureExecution

Fields of ProcedureExecution

rid string

Fields of ProcedureExecutionMetadata

rid string
procedure_rid string: The procedure template rid this execution is based on.
procedure_commit_id string: The commit ID of the procedure template this execution is based on. This can be overridden at the node level for individual nodes.
title string: At least 1 character.
description string
labels array of string
properties map of string to string
created_by string
created_at string (date-time)
updated_by string
updated_at string (date-time)
started_at string (date-time): Will be unset until the execution transitions from NOT_STARTED to IN_PROGRESS.
started_by string
finished_at string (date-time): Will be unset until the execution transitions from IN_PROGRESS to a terminal state.
finished_by string
aborted_at string (date-time): Will be true/set if the execution is the ABORTED terminal state.
aborted_by string
failed_at string (date-time): Will be set if the execution is in the ERRORED terminal state.
failed_by string
failed_reason string
asset_rids array of string: Assets which this execution has acted on in completed steps (e.g. through an event creation action).
is_archived boolean

Fields of ProcedureExecutionState

global_fields map of string to FieldOutput

The current values for the global fields in the procedure.

Fields of FieldOutput

one of 10 fields

asset_rid

asset_rid string: If a global field is not yet defined, I think it’s just not present in the global_fields map option (buf.validate.oneof) = {required: true};

string_value

string_value string

double_value

double_value number

boolean_value

boolean_value boolean

int_value

int_value integer (int64)

strings_value

strings_value Strings

Fields of Strings

values array of string

ingest_job_rid

ingest_job_rid string

run_rid

run_rid string

file_upload_value

file_upload_value FileUploadFieldValue

Fields of FileUploadFieldValue

s3_upload S3UploadFileValue

Fields of S3UploadFileValue

s3_path string: The S3 path where the uploaded file is stored At least 1 character.
file_name string: The original filename of the uploaded file At least 1 character.
file_type string: The MIME type of the uploaded file Following the convention of https://developer.mozilla.org/en-US/docs/Web/API/Blob/type (from which the File api inherits, we will accept an empty string)

multi_file_upload_value

multi_file_upload_value MultiFileUploadFieldValue

Fields of MultiFileUploadFieldValue

uploads array of FileUploadFieldValue: The list of uploads

nodes map of string to ProcedureExecutionNode

A map from execution node ID to the execution node.

Fields of ProcedureExecutionNode

one of section, step

section

A section node is a visual grouping of other sections and steps. Execution sections are static and do not have execution state.

Fields of ProcedureExecutionSectionNode

id string: Unique identifier of this execution node. At least 1 character.
template_node_id string: Unique identifier of the template node this execution node is based on. At least 1 character.
title string: Title of this section. Uses the template section’s title and cannot be changed in execution. At least 1 character.
description string: Description of this section. Uses the template section’s description and cannot be changed in execution.
template_commit_id string: If set, the commit ID of the procedure template this section is based on. Otherwise, the section is based on the template commit specified at the top level of the execution.

step

Execution steps are the interactive steps in a procedure.

Fields of ProcedureExecutionStepNode

id string

Unique identifier of this execution node. At least 1 character.

template_node_id string

Unique identifier of the template node this execution node is based on. At least 1 character.

is_outdated boolean

Execution steps become “outdated” once any upstream steps are re-run An outdated execution step should not be further modified.