> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siftstack.com/llms.txt
> Use this file to discover all available pages before exploring further.
# runs
> sift/runs/v2/runs.proto
## Services
*RPC methods exposed by this API.*
### RunService
| Method | Request | Response | Description |
| :------------------------------------- | :---------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| GetRun | [GetRunRequest](#getrunrequest) | [GetRunResponse](#getrunresponse) | Retrieve a run. |
| ListRuns | [ListRunsRequest](#listrunsrequest) | [ListRunsResponse](#listrunsresponse) | Retrieve runs using an optional filter. |
| CreateRun | [CreateRunRequest](#createrunrequest) | [CreateRunResponse](#createrunresponse) | Create a run. |
| CreateAdhocRun | [CreateAdhocRunRequest](#createadhocrunrequest) | [CreateAdhocRunResponse](#createadhocrunresponse) | Create adhoc run, this is used to create a run after the data has been ingested |
| UpdateRun | [UpdateRunRequest](#updaterunrequest) | [UpdateRunResponse](#updaterunresponse) | Updates an existing run using using the list of fields specified in `update_mask`. |
| DeleteRun | [DeleteRunRequest](#deleterunrequest) | [DeleteRunResponse](#deleterunresponse) | Permanently delete a given run. In order for a run to be deleted it must have a set `stop_time`. Deprecated: Use update with is\_archived. |
| StopRun | [StopRunRequest](#stoprunrequest) | [StopRunResponse](#stoprunresponse) | Set the stop time of a run to the current time. To set the stop time of a run to an arbitrary time see `UpdateRun`. |
| GetFilterFields | [GetFilterFieldsRequest](#getfilterfieldsrequest) | [GetFilterFieldsResponse](#getfilterfieldsresponse) | Returns the available filter fields for the ListRuns CEL filter. |
| ValidateRunFilter | [ValidateRunFilterRequest](#validaterunfilterrequest) | [ValidateRunFilterResponse](#validaterunfilterresponse) | Validates a CEL filter expression against the available run filter fields. Returns an error message if the expression is invalid, or an empty error\_message if valid. |
| CreateAutomaticRunAssociationForAssets | [CreateAutomaticRunAssociationForAssetsRequest](#createautomaticrunassociationforassetsrequest) | [CreateAutomaticRunAssociationForAssetsResponse](#createautomaticrunassociationforassetsresponse) | Associates a list of assets with a given run. |
## Messages
*Data models used across requests/responses.*
### CreateAdhocRunRequest
The request for a call to `RunService_CreateAdhocRun` to create an adhoc run.
| Field | Type | Label | Description |
| :---------- | :---------------------------------------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------- |
| name | string | | The name that will be assigned to the new run. |
| description | string | | A description about the new run. |
| start\_time | google.protobuf.Timestamp | | The time at which data ingestion began for this new run. It must be before the `stop_time` |
| stop\_time | google.protobuf.Timestamp | | The time at which data ingestion concluded for this new run. |
| asset\_ids | string | repeated | A list of asset IDs to associate with the new run. |
| tags | string | repeated | Tags to associate with the new run. |
| metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | The metadata values associated with this run. |
| client\_key | string | optional | An arbitrary user-chosen key that uniquely identifies this run. Optional, though it is recommended to provide. |
### CreateAdhocRunResponse
The response of a call to `RunService_CreateAdhocRun` containing the newly created adhoc run.
| Field | Type | Label | Description |
| :---- | :---------- | :---- | :---------- |
| run | [Run](#run) | | |
### CreateAutomaticRunAssociationForAssetsRequest
| Field | Type | Label | Description |
| :----------- | :----- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| run\_id | string | | The ID of the run to associate the asset with. |
| asset\_names | string | repeated | A list of asset names to automatically associate with the run. Any data that is received for these assets will automatically added to the run. This applies even if the run has concluded, so long as the new data contains timestamps that are between the `start_time` and `stop_time`. If any of the assets are already associated with a different run whose run period (the period between `start_time` and `end_time`) overlaps with the requested run period, an error will be returned. |
### CreateAutomaticRunAssociationForAssetsResponse
*This message has no fields.*
### CreateRunRequest
The request of a call to `RunService_CreateRuns` to create a new run.
| Field | Type | Label | Description |
| :---------------------- | :---------------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| name | string | | The name that will be assigned to the new run. |
| description | string | | A description about the new run. |
| tags | string | repeated | Tags to associate with the new run. |
| start\_time | google.protobuf.Timestamp | | The time at which data ingestion begins for this new run. It must be before the `stop_time`, and it must be provided if a `stop_time` is provided. Important note: `start_time` will be automatically computed during data ingestion and will be set based on the timestamp of the data for this run. |
| stop\_time | google.protobuf.Timestamp | | The time at which data ingestion for this new run concludes. Important note: `stop_time` will be automatically computed during data ingestion and will be set based on the timestamp of the data for this run. |
| organization\_id | string | | An organization ID is only required if the user belongs to multiple organizations. |
| client\_key | string | optional | An arbitrary user-chosen key that uniquely identifies this run. Optional, though it is recommended to provide. |
| metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | The metadata values associated with this run. |
| create\_default\_report | bool | optional | Whether to create a default report for this run. This facilitates getting the report ID for live rules that will be automatically created for this run which can streamline programatically creating Campaigns. Defaults to false if not specified (This default can be changed for your organization by Sift. Contact support to change this default behavior.). |
### CreateRunResponse
| Field | Type | Label | Description |
| :---- | :---------- | :---- | :---------- |
| run | [Run](#run) | | |
### DeleteRunRequest
The request for a call to `RunService_DeleteRun`.
| Field | Type | Label | Description |
| :------ | :----- | :---- | :---------- |
| run\_id | string | | |
### DeleteRunResponse
The response of a call to `RunService_DeleteRun`.
*This message has no fields.*
### GetFilterFieldsRequest
The request for a call to `RunService_GetFilterFields`.
*This message has no fields.*
### GetFilterFieldsResponse
The response of a call to `RunService_GetFilterFields`.
| Field | Type | Label | Description |
| :------------- | :-------------------------------------------------------- | :------- | :---------- |
| filter\_fields | [sift.common.v1.FilterField](#sift-common-v1-filterfield) | repeated | |
### GetRunRequest
The request for a call to `RunService_GetRun` to retrieve run.
| Field | Type | Label | Description |
| :------ | :----- | :---- | :----------------------------- |
| run\_id | string | | The ID of the run to retrieve. |
### GetRunResponse
The response of a call to `RunService_GetRun` containing the requested run.
| Field | Type | Label | Description |
| :---- | :---------- | :---- | :---------- |
| run | [Run](#run) | | |
### ListRunsRequest
The request for a call to `RunService_ListRuns` to retrieve runs.
| Field | Type | Label | Description |
| :---------- | :----- | :---- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| page\_size | uint32 | | The maximum number of runs to return. The service may return fewer than this value. If unspecified, at most 50 runs will be returned. The maximum value is 1000; values above 1000 will be coerced to 1000. |
| page\_token | string | | A page token, received from a previous `ListRuns` call. Provide this to retrieve the subsequent page. When paginating, all other parameters provided to `ListRuns` must match the call that provided the page token. |
| filter | string | | A [Common Expression Language (CEL)](https://github.com/google/cel-spec) filter string. Available fields to filter by are `run_id` `organization_id`, `asset_id`, `asset_name`, `client_key`, `name`, `description`, `created_by_user_id`, `modified_by_user_id`, `created_date`, `modified_date`, `start_time`, `stop_time`, `tag_id`, `asset_tag_id`, `duration`, 'duration\_string', `annotation_comments_count`, `annotation_state`, `archived_date`, `is_archived`, and `metadata`. Metadata can be used in filters by using `metadata.{metadata_key_name}` as the field name. `duration` is in the format of elapsed seconds and `duration_string` allows for `h`, `m`, `s`, `ms` suffixes (example: \`duration\_string > duration('10h')) For further information about how to use CELs, please refer to [this guide](https://github.com/google/cel-spec/blob/master/doc/langdef.md#standard-definitions). For more information about the fields used for filtering, please refer to [this definition](/docs/api/grpc/protocol-buffers/runs#run). Optional. |
| order\_by | string | | How to order the retrieved runs. Formatted as a comma-separated string i.e. "FIELD\_NAME\[ desc],...". Available fields to order\_by are `name`, `description`, `created_date`, `modified_date`, `start_time`, and `stop_time`. If left empty, items are ordered by `created_date` in descending order (newest-first). For more information about the format of this field, read [this](https://google.aip.dev/132#ordering) Example: "created\_date desc,modified\_date" |
### ListRunsResponse
The response of a call to `RunService_ListRuns` containing requested runs.
| Field | Type | Label | Description |
| :---------------- | :---------- | :------- | :---------- |
| runs | [Run](#run) | repeated | |
| next\_page\_token | string | | |
### Run
| Field | Type | Label | Description |
| :--------------------- | :---------------------------------------------------------------- | :------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| run\_id | string | | |
| created\_date | google.protobuf.Timestamp | | |
| modified\_date | google.protobuf.Timestamp | | |
| created\_by\_user\_id | string | | |
| modified\_by\_user\_id | string | | |
| organization\_id | string | | |
| start\_time | google.protobuf.Timestamp | optional | |
| stop\_time | google.protobuf.Timestamp | optional | |
| is\_pinned | bool | | |
| name | string | | |
| description | string | | |
| tags | string | repeated | |
| default\_report\_id | string | | |
| client\_key | string | optional | |
| metadata | [sift.metadata.v1.MetadataValue](#sift-metadata-v1-metadatavalue) | repeated | The metadata values associated with this run. |
| asset\_ids | string | repeated | |
| archived\_date | google.protobuf.Timestamp | optional | |
| is\_adhoc | bool | | |
| is\_archived | bool | | Whether the Run is archived. This is inferred from whether archived\_date is set. |
| duration | google.protobuf.Duration | optional | The duration of the run. Calculated as the difference between stop\_time and start\_time. If the run is ongoing (no stop\_time), this represents the duration from start\_time to current time. |
### StopRunRequest
The request for a call to `RunService_StopRun` to stop a run.
| Field | Type | Label | Description |
| :------ | :----- | :---- | :---------- |
| run\_id | string | | |
### StopRunResponse
The response of a call to `RunService_StopRun` to stop a run.
*This message has no fields.*
### UpdateRunRequest
The request for a call to `RunService_UpdateRun` to update an existing run.
| Field | Type | Label | Description |
| :----------- | :------------------------------------------------------ | :---- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| run | [Run](#run) | | The run to update. The run's `run_id` field is used to identify the run to update and is required. |
| update\_mask | [google.protobuf.FieldMask](#google-protobuf-fieldmask) | | The list of fields to be updated. The fields available to be updated are `name`, `description`, `start_time`, `stop_time`, `is_pinned`, `client_key`, `tags`,`is_archived`, and `metadata`. Important Note: When updating the `start_time`, please be aware that if a subsequent data ingestion commences for this run, the `start_time` will be automatically overwritten and set to the timestamp corresponding to the beginning of the latest run. Additionally, `client_key` can only be set once either in run creation or in update. Any subsequent attempt to update `client_key` will result in an error. |
### UpdateRunResponse
The response of a call to `RunService_UpdateRun` containing the updated run.
| Field | Type | Label | Description |
| :---- | :---------- | :---- | :---------- |
| run | [Run](#run) | | |
### ValidateRunFilterRequest
The request for a call to `RunService_ValidateRunFilter`.
| Field | Type | Label | Description |
| :----- | :----- | :---- | :------------------------------------- |
| filter | string | | The CEL filter expression to validate. |
### ValidateRunFilterResponse
The response of a call to `RunService_ValidateRunFilter`.
| Field | Type | Label | Description |
| :------------- | :----- | :---- | :------------------------------------------------------------------------------------ |
| error\_message | string | | Empty string if the filter is valid; otherwise contains the validation error message. |
## Enums
*Allowed constant values used in message fields.*