Anomaly Detection¶

Anomaly detection in TSI is designed to detect deviations from "normal" operating behavior. The workflow consists of Learn (training a model on a baseline period) and Evaluation (applying the model to detect anomalies in new data).

Jupyter Notebook tutorials¶

Anomaly Detection: Creating and monitoring models for individual signals

Create an anomaly model¶

This flow initiates the learning process for an anomaly model using a defined dataspec.

Method	Path
`POST`	`/api/1.3/accounts/{account_id}/flows`

Request Body Fields

Field	Type	Required	Description
`name`	`string`	Yes	A user-defined name for the flow.
`flowType`	`string`	Yes	Must be set to `ANOMALYLEARN`.
`description`	`string`	No	A short summary of the flow's purpose.
`spec`	`object`	Yes	Specifications for the model training.
`spec.workspace`	`string`	Yes	The ID of the workspace where the model will be created.
`spec.modelName`	`string`	No	Custom name for the model. Defaults to `{{workspaceName}}/{{modelType}}/M[{{index}}]`.
`spec.dataspec`	`object`	Yes	Defines the time ranges and signals used for training.

Usage Examples

Option 1: New DataspecOption 2: Existing Dataspec

{
  "name": "create anomaly model",
  "flowType": "ANOMALYLEARN",
  "description": "creating anomaly model basic",
  "spec": {
    "workspace": "{{id_of_the_workspace}}",
    "modelName": "basic_model",
    "dataspec": {
      "name": "learn range 10 days anomaly",
      "specs": [
        { 
          "timeRanges": [
            {
              "startTime": "2026-01-01T00:00:00Z", 
              "endTime": "2026-01-10T00:00:00Z"
            }
          ],
          "signals": [
            {"signal": "{{signal_id}}","name": "sensor1"}
          ]
        }
      ]
    }
  }
}

{
  "name": "retrain anomaly model",
  "flowType": "ANOMALYLEARN",
  "spec": {
    "workspace": "{{id_of_the_workspace}}",
    "modelName": "basic_model_v2",
    "dataspec": {
      "id": "{{dataspec_id}}"
    }
  }
}

Flow Completion

At flow completion, a dataspec ID is generated which can be reused for future flows. The created model saves the history of the learning range and signals.

Evaluate an anomaly model¶

Apply an existing anomaly model to historical data to generate anomaly scores.

Method	Path
`POST`	`/api/1.3/accounts/{account_id}/flows`

Parameters

Field	Type	Required	Description
`name`	`string`	Yes	Name for the evaluation task.
`flowType`	`string`	Yes	Must be set to `ANOMALYEVAL`.
`spec.model`	`string`	Yes	The ID of the anomaly model to evaluate.
`spec.workspace`	`string`	Yes	The ID of the workspace.
`spec.dataspec`	`object`	Yes	A configuration object that denotes the time range per signal. It allows for precise data selection and can be reused once created.
`spec.outputsignalPrefix`	`string`	Conditional*	Used to name newly created output Connected Sources (Format: `{{prefix}}/{{model_output_schema_name}}`). Required if `outputsignals` is not provided.
`spec.outputsignals`	`array`	Conditional*	Must match the model output schema. Used when mapping results to specific pre-existing signals. Required if `outputsignalPrefix` is not provided.

Usage Examples

Option 1: Output PrefixOption 2: Existing Output SignalsOption 3: Existing Dataspec ID

{
  "name": "eval 1 on anomaly model",
  "flowType": "ANOMALYEVAL",
  "spec": {
    "model": "{{insight_model_id}}",
    "workspace": "{{workspace_id}}",
    "dataspec": {
      "name": "anomaly eval range 1",
      "specs": [
        { 
          "timeRanges": [
            {
              "startTime": "2026-01-15T00:00:00Z", 
              "endTime": "2026-01-20T00:00:00Z"
            }
          ],
          "signals": [
            {"signal": "{{signal_id}}","name": "sensor1"}
          ]
        }
      ]
    },
    "outputsignalPrefix": "basic-test1"
  }
}

{
  "name": "eval 2 on anomaly model",
  "flowType": "ANOMALYEVAL",
  "spec": {
    "model": "{{insight_model_id}}",
    "workspace": "{{workspace_id}}",
    "dataspec": {
      "name": "anomaly eval range 2",
      "specs": [
        { 
          "timeRanges": [
            {
              "startTime": "2026-01-20T00:00:00Z", 
              "endTime": "2026-01-29T00:00:00Z"
            }
          ],
          "signals": [
            {"signal": "{{signal_id}}","name": "sensor1"}
          ]
        }
      ]
    },
    "outputsignals": [
      {
        "signal": "{{signal_id}}", 
        "name": "anomalyscore" 
      }
    ]
  }
}

{
  "name": "eval with existing dataspec",
  "flowType": "ANOMALYEVAL",
  "spec": {
    "model": "{{insight_model_id}}",
    "workspace": "{{workspace_id}}",
    "dataspec": {
      "id": "{{dataspec_id}}"
    },
    "outputsignalPrefix": "batch-eval-01"
  }
}

Flow Completion

Upon completion, an Eval object is created in the workspace containing references to the input signalset, output signalset, and the model.

Learn incrementally¶

Incremental learning allows you to build upon an existing model by adding new data to represent "normal" behavior or reinforcing learning within a specific range. This uses the ANOMALYLEARN flow type, but requires the model ID of the existing model you wish to update.

Method	Path
`POST`	`/api/1.3/accounts/{account_id}/flows`

Request Body Fields

Field	Type	Required	Description
`model`	`string`	Yes	The ID of the original Anomaly Model to be incrementally learned upon. Providing this ID triggers the incremental logic rather than creating a brand-new model.
`name`	`string`	Yes	A user-defined name for the incremental learning flow.
`flowType`	`string`	Yes	Must be set to `ANOMALYLEARN`.
`spec.dataspec`	`object`	Yes	Defines the new time ranges and signals to be added to the model's knowledge base.

Usage Example

Sample Payload

{
   "name": "Incremental_Learn_Pump_v1",
   "flowType": "ANOMALYLEARN",
   "spec": {
        "model": "1338619098414317568",
        "workspace": "{{id_of_the_workspace}}",
        "dataspec": {
            "name": "incremental_baseline_extension",
            "specs": [
                {
                    "timeRanges": [
                        {
                            "startTime": "2026-01-23T11:13:26.000Z",
                            "endTime": "2026-01-23T12:37:30.000Z"
                        }
                    ],
                    "signals": [
                        {
                            "signal": "1332064119748558848",
                            "name": "sensor1"
                        }
                    ]
                }
            ]
        }
    }
}

Note

It is not necessary to include the original time ranges from the initial training; only the new baseline data is required for the update.