---
title: "SegmentML"
description: "<p>SegmentML provides a framework for building custom machine learning</p><p>models directly in Lytics.  Lytics SegmentML models are self-training,</p><p>continuously-updating and real-time.</p><p>SegmentML models are built by identifying:</p><p>1. A segment of users, called the **Target Segment** who exhibit behavior for *prediction*,</p><p>2. A segment of users, called the **Source Segment** to be candidates for model *evaluation*, or scoring.</p><p>Models are built with a variety of pre-selected candidate features, which include behavioral scores and content affinities, and can additionally support any custom field available in Lytics user profiles.</p><p>Attributes concerning the SegmentML model's setup configuration are detailed in **SegmentML Create**. Attributes concerning the model's results are defined in **SegmentML Model Fetch**.</p><p>Generic attributes from SegmentML model GET and POST:</p><p>| field          | DataType         | Description   |</p><p>|--------------  |------------------|---------------|</p><p>| name           | string           | The model's name</p><p>| state          | string           | The state of the model: Either *building*, *invalid*, or *complete*</p><p>| reason         | string           | If the state is *invalid* the reason will denote the error</p><p>| created        | string           | Date and time the model was created</p>"
url: "https://www.contentstack.com/docs/developers/apis/lytics-api/v1/segmentml"
product: "Contentstack"
doc_type: "guide"
audience:
  - developers
  - admins
version: "current"
last_updated: "2026-11-05"
---

# SegmentML

SegmentML provides a framework for building custom machine learning

models directly in Lytics. Lytics SegmentML models are self-training,

continuously-updating and real-time.

SegmentML models are built by identifying:

1\. A segment of users, called the \*\*Target Segment\*\* who exhibit behavior for \*prediction\*,

2\. A segment of users, called the \*\*Source Segment\*\* to be candidates for model \*evaluation\*, or scoring.

Models are built with a variety of pre-selected candidate features, which include behavioral scores and content affinities, and can additionally support any custom field available in Lytics user profiles.

Attributes concerning the SegmentML model's setup configuration are detailed in \*\*SegmentML Create\*\*. Attributes concerning the model's results are defined in \*\*SegmentML Model Fetch\*\*.

Generic attributes from SegmentML model GET and POST:

| field | DataType | Description |

|-------------- |------------------|---------------|

| name | string | The model's name

| state | string | The state of the model: Either \*building\*, \*invalid\*, or \*complete\*

| reason | string | If the state is \*invalid\* the reason will denote the error

| created | string | Date and time the model was created

## SegmentML Model Fetch

### SegmentML Model Fetch

**GET** `/api/segmentml/{id}`

Get a SegmentML model.

Additional atttributes from a completed SegmentML model GET response:

| field | DataType | Description |

|-----------------------|------------------|---------------|

| features: kind | string | The field is either a Lytics Segment feature (\*segment\*), a lql/user-field feature (\*lql\*), a Lytics Behavioral Score feature (\*score\*), or a Lytics Content Affinity feature (\*content\*)

| features: fieldtype | string | Field type is either \*numeric\* or \*categorical\*

| features: name | string | The name of a field

| features: importance | number | The relative importance of a field in the model

| features: correlation | number | Correlation between specific field and target

| features: impact | object | The impact object details the Lift and shows the marginal effect of a feature on the predicted outcome of the model

| mse | number | Mean-squared error value

| rsq | number | R-squared value or coefficient of determination

| false\_negative | number | The number of users in the source segment who are predicted to be in the target segment.

| false\_positive | number | The number of users in the target segment who are not predicted to be in the target segment.

| true\_negative | number | The number of users in the source segment who are not predicted to be in the target segment.

| true\_positive | number | The number of users in the target segment who are predicted to be in the target segment.

| success | \[\]number | Number of successful predictions for a given prediction value

| failure | \[\]number | Number of failed predictions for a given prediction value

| auc | number | Area under the ROC curve

| threshold | number | Optimal decision threshold to minimize false-positives and false-negatives

| accuracy | number | A value that represents the accuracy of the model; scale ranges from 0 (least accurate) to 10 (most accurate).

| reach | number | A value that represents the number of source users that look like target users; scale ranges from 0 (low reach) to 10 (high reach).

| model\_health | number | The overall health of the model (i.e. "healthy", "unhealthy")

| msgs | number | Messages for the user about the model with levels of severity (i.e. "debug", "info", "warn", "error")

To learn more about the metrics false negative, false positive etc., check out \[binary classification\](https://en.wikipedia.org/wiki/Binary\_classification).

\`\`

\# Curl example of getting a SegmentML model

curl -s -J -XGET "https://api.lytics.io/api/segmentml/all::smt\_power" -H "Authorization: $LIOKEY"

\`\`

#### URL Parameters

- **id** (required)
  ID of the SegmentML model to retrieve, of the form SOURCE\_SLUG::TARGET\_SLUG.

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
OK
```

## SegmentML Delete

### SegmentML Delete

**DELETE** `/api/segmentml/{id}`

Delete a SegmentML model.

\`\`sh

\# Curl example of deleting a SegmentML model

curl -s -J -XDELETE "https://api.lytics.io/api/segmentml/all::smt\_power" -H "Authorization: $LIOKEY"

\`\`

#### URL Parameters

- **id** (required)
  ID of the SegmentML model to delete, of the form SOURCE\_SLUG::TARGET\_SLUG.

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
No Content
```

## SegmentML Create

### SegmentML Create

**POST** `/api/segmentml`

Create a new SegmentML model.

Model configuration can be specified either through sending the options

as a flat JSON object POST body or through URL parameters on the request.

\`\`sh

\# Curl example of creating a SegmentML model

curl -s -J -XPOST "https://api.lytics.io/api/segmentml" -H "Authorization: $LIOKEY" -d '

{

"source": "all",

"target": "smt\_power",

"use\_scores": true

}

'

\`\`

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.
- **source** (required)
  ID or slug of the source segment.
- **target** (optional)
  ID or slug of the target segment. \*\*Required\*\* if target field is not supplied.
- **use_scores** (optional)
  Include raw behavioral scores as features in the model (usually very useful).
- **target_field** (optional)
  Slug of the target field. Cannot provide both a target and a target field, hence required if target segment is not indicated (see above).
- **use_content** (optional)
  If true, include content affinities as features in the model.
- **aspect_collections** (optional)
  List of Segment Collections to include in the model. Possible values are "email", "web", "support", "mobile", "commerce", "behaviors", "content".
- **additional_fields** (optional)
  List of additional user fields to include in the model.
- **model_only** (optional)
  Build the model without scoring each user. This is useful during model building exercises when comparing efficiency and accuracy between models. Set true by default unless \*\*evalonly\*\* is selected.
- **eval_only** (optional)
  If true, a previously built model is used to rescore users. Only the source and target parameters are needed in the API call to to identify which model to use.
- **auto_tune** (optional)
  If true, enable auto-tune feature selection.
- **tune_model** (optional)
  If true, model tuning parameters are optimized before any models are built. Experimental.
- **tags** (optional)
  Includes tags to be associated with the model.
- **re_run** (optional)
  If true, re-run the model every week.
- **save_segments** (optional)
  If true, this saves three different segments:

1) Users from source and target segments who "look like" users from the target segment.

2) Users not in the target segment.

3) Users from the source segment who look like users from the target segment.
- **as_is** (optional)
  If true, do not remove any of the model features when creating the model.
- **num_to_train** (optional)
  The number of samples to collect from both the source and target segment for feature matrices. Defaults to 5,000.
- **cor_threshold** (optional)
  Threshold (0.0-1.0) at which to remove correlated features.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "name": "test_rf",
  "state": "building",
  "reason": "",
  "created": "2018-07-10T16:10:54.456003352-07:00",
  "conf": {
    "source": {
      "aid": 123,
      "account_id": "lol",
      "id": "",
      "name": "all",
      "is_public": false,
      "slug_name": "",
      "description": "",
      "author_id": "",
      "updated": "0001-01-01T00:00:00Z",
      "created": "2018-07-10T16:10:54.442558895-07:00",
      "invalid": false,
      "invalid_reason": "",
      "deleted": false,
      "datemath_calc": false,
      "forward_datemath": false,
      "save_hist": false,
      "schedule_exit": false,
      "tags": null
    },
    "target": {
      "aid": 123,
      "account_id": "lol",
      "id": "",
      "name": "goal",
      "is_public": false,
      "slug_name": "",
      "description": "",
      "author_id": "",
      "updated": "0001-01-01T00:00:00Z",
      "created": "2018-07-10T16:10:54.442559277-07:00",
      "invalid": false,
      "invalid_reason": "",
      "deleted": false,
      "datemath_calc": false,
      "forward_datemath": false,
      "save_hist": false,
      "schedule_exit": false,
      "tags": null
    },
    "target_field": null,
    "model_name": "",
    "additional": null,
    "collections": null,
    "collect": 0,
    "use_scores": true,
    "use_content": false,
    "build_only": false,
    "auto_tune": false
  }
}
```

## SegmentML Dependencies

### SegmentML Dependencies

**GET** `/api/segmentml/_dependencies/{modelname}`

#### URL Parameters

- **modelname** (required)
  Name of the model to get dependencies for.

#### Query Parameters

- **account_id** (optional)
  Your Lytics account ID.

#### Headers

- **Authorization** (optional)

#### Sample Response

```json
{
  "message": "success",
  "status": 200,
  "data": {
    "fields": {
      "lytics_score_frequency": [
        [
          1,
          0.5283225806451614
        ],
        [
          4.6,
          0.5283225806451614
        ],
        [
          8.2,
          0.5281612903225807
        ]
      ],
      "lytics_score_intensity": [
        [
          1,
          0.5283225806451614
        ],
        [
          4.6,
          0.5283225806451614
        ],
        [
          8.2,
          0.5281612903225807
        ]
      ]
    }
  }
}
```