Skip to main content
A Run is a distinct grouping of time-series data capture from one or more Assets. By organizing telemetry into Runs, you can isolate specific events, tests, or missions, and investigate patterns, assess performance, and diagnose anomalies within a contextual timeframe. The Run API supports this concept:
  • start_time, stop_time (time window)
  • asset_ids (one run can span multiple assets)
  • computed duration based on stop-start (or ongoing)
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

To create a run, use the RunService.CreateRun endpoint. The response will contain the newly created run details:
  • CreateRunResponse returns run Run which contains run_id.
Use the returned run ID when streaming data.
Client KeysThe Run message has an optional client_key field that lets you specify a unique identifier for this resource. Although it is optional, it is recommended because it makes querying runs much more convenient. A client key can be provided during run creation. The client_key can only be set once (create or first update).

​
Retrieving Runs

Sift provides the following 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 ways 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. For example, using ingestion-config-based-streaming:
Retrieving a Run IDIf a run ID is not available, you can 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.