Skip to main content
A run represents a discrete time period of data capture from one or more assets. While not mandatory for data ingestion, runs facilitate data identification in Sift and the API. For a formal definition of a run, refer to the protocol buffers documentation. General Workflow:
  1. Create a run
  2. Stream data for an asset, including the run ID in each request
  3. View the run in Sift

​
Creating a Run

  1. Use the RunService.CreateRun endpoint
  2. The response will contain the newly created run details
  3. Use the returned run ID when streaming data
Client KeysThe Run message has an optional client_key field that gives users the ability to specify their own unique identifier for this resource. Although it is optional, it is highly recommended to be provided as it will make querying runs much more convenient. A client key can be provided during run creation

​
Retrieving Runs

Sift provides two methods for retrieving runs:
  • RunService.GetRun
    • Requires a specific run ID
    • Useful when the run ID is known
  • RunService.ListRuns
    • Allows searching for runs using various criteria
    • Useful when the exact run ID is unknown
    • Search parameters include:
Example of querying a run by client_key: 
curl -G -H "Authorization: Bearer $API_TOKEN" -d "filter=client_key=='example_client_key'" $SIFT_REST_URL/api/v2/runs

​
Updating a Run

To update an existing run, use the RunService.UpdateRun endpoint.

​
Using the Run

There are two primary mechanism to associate run to asset(s) data:
  • Manual Association
  • Automatic Association

​
Manual Association

For all data ingestion mechanisms, you can manually provide a run ID. Example, using ingestion-config-based-streaming:
Retrieving a Run IDIf you don’t have a run ID handy you may query your runs first to get the run ID.

​
Automatic Association

Use the RunService.CreateAutomaticRunAssociationForAssets endpoint to:
  • Associate a run with specific assets in advance
  • Assets do not need to exist beforehand
Benefits:
  • Data arriving for specified assets automatically associates with the run
  • No need to include run ID in each ingestion request
Note: If one of the assets specified has an ongoing run, that is, its stop_time is not set, then the CreateAutomaticRunAssociationForAssets endpoint return an error.
Non-Standard WorkflowIf you use the automatic association method you should not include the run ID in the IngestWithConfigDataStreamRequest when streaming data for the associated asset.Note that this is not a standard workflow and it is recommended to use the manual association method.