Documentation / Developer / Lytics APIs

ML

The ML API provides the ability to create, update, delete and modify ML models in Lytics.

The ML resource has the following attributes:

FieldDatatypeDescription
idstringunique id, Lytics assigned
namestringName of the ML model
labelstringUser assigned label
statestringState of the model (either 'completed', 'invalid', or 'building')
sourcestringID of the source audience
targetstringID of the target audience
typestringModel-type (either 'rf' or 'gbm')
is_healthybooleanIndicates whether a model is healthy
is_activebooleanIndicates whether a model is active
createdDateCreated date
updatedDateLast Updated date
configConfigML model configuration

The `Config` object has the following attributes:
FieldDatatypeDescription
use_scoresbooleanInclude Lytics Behavioral Scores as features in the model
use_contentbooleanInclude Lytics Content Affinities as features in the model
collectintegerThe number of samples to collect when creating the model (Default: 5000)
build_onlybooleanBuild the model without scoring each user. This is useful during model building exercises when comparing efficiency and accuracy between models
auto_tunebooleanEnable auto-tune feature selection
tune_modelbooealnEnable model parameter optimization
re_runbooleanRe-train the model on a weekly basis
additional[]stringList of additional user fields to include in the model

ML List

/api/ml

Get a list of all ML models for an account. For more information about ML models, consult the api/ml/:id/summary API below.

GET

ML List

/api/ml

Response 200

Headers
Content-Type: application/json
Body
{
    "data": [
        {
            "aid": 1234,
            "id": "2120ae0818414cba840b68308710b98a",
            "name": "ML: Grow Customer Base",
            "label": "Predictive Model to grow customer base",
            "state": "complete",
            "source": "cf21ba3ceb194961b964358ee92ec4a9",
            "target": "e34563f98bc848b7abb17c4a0499968c",
            "type": "rf",
            "is_healthy": true,
            "is_active": true,
            "created": "2020-08-10T16:00:00.123456789-07:00",
            "updated": "2020-08-10T16:00:00.123456789-07:00",
            "config": {
                "collect": 5000,
                "use_scores": true,
                "use_content": true,
                "build_only": false,
                "auto_tune": false,
                "model_type": "rf",
                "re_run": true,
                "tune_model": true
            }
        }
    ]
}

ML

/api/ml/{id}

Get a ML model by ID

Parameters
idstring (required)
Ex: abcdefg123456
id of a ML model
GET

ML Fetch

/api/ml/{id}

Response 200

Headers
Content-Type: application/json
Body
{
    "data": {
        "aid": 1234,
        "id": "2120ae0818414cba840b68308710b98a",
        "name": "ML: Grow Customer Base",
        "label": "Predictive Model to grow customer base",
        "state": "complete",
        "source": "cf21ba3ceb194961b964358ee92ec4a9",
        "target": "e34563f98bc848b7abb17c4a0499968c",
        "type": "rf",
        "is_healthy": true,
        "is_active": true,
        "created": "2020-08-10T16:00:00.123456789-07:00",
        "updated": "2020-08-10T16:00:00.123456789-07:00",
        "config": {
            "collect": 5000,
            "use_scores": true,
            "use_content": true,
            "build_only": false,
            "auto_tune": false,
            "model_type": "rf",
            "re_run": true,
            "tune_model": true
        }
    }
}
PUT

ML Update

/api/ml/{id}

Update a ML Model. Currently only the is_active and label attributes can be updated.

# update label 
curl -s -XPOST "https://api.lytics.io/api/ml/abcdefg123456" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d '{ "label": "my new label" }' 

http PUT "https://api.lytics.io/api/ml/abcdefg123456" key==$LIOKEY label=="my new label"

# update is_active
curl -s -XPOST "https://api.lytics.io/api/ml/abcdefg123456" \
    -H "Content-type: application/json" \
    -H "Authorization: $LIOKEY" \
    -d '{ "is_active": true }' 

http PUT "https://api.lytics.io/api/ml/abcdefg123456" key==$LIOKEY is_active==false

Response 200

Headers
Content-Type: application/json
Body
{
    "data": {
        "aid": 1234,
        "id": "2120ae0818414cba840b68308710b98a",
        "name": "ML: Grow Customer Base",
        "label": "Predictive Model to grow customer base",
        "state": "complete",
        "source": "cf21ba3ceb194961b964358ee92ec4a9",
        "target": "e34563f98bc848b7abb17c4a0499968c",
        "type": "rf",
        "is_healthy": true,
        "is_active": true,
        "created": "2020-08-10T16:00:00.123456789-07:00",
        "updated": "2020-08-10T16:00:00.123456789-07:00",
        "config": {
            "collect": 5000,
            "use_scores": true,
            "use_content": true,
            "build_only": false,
            "auto_tune": false,
            "model_type": "rf",
            "re_run": true,
            "tune_model": true
        }
    }
}
DELETE

ML Delete

/api/ml/{id}

Delete a ML Model

Response 204

POST

ML Create

/api/ml/{id}

Create a new ML model.

# Create a simple model 
http POST "https://api.lytics.io/api/ml" key==$LIOKY \
    source==<source_segment_id> \ 
    target==<target_segment_id> \
    label=="my new model"

# Create a custom model 
echo '{
    "source": "<source_segment_id>",
    "target": "<target_segmente_id>",
    "name": "Grow Customer Base",
    "label": "Model to increase customer base",
    "config": {
        "use_scores": true,
        "use_content": true,
        "additional": [ "city", "visit_ct", "utm_mediums" ]
    }
}' | http POST "https://api.lytics.io/api/ml" key==$key

Response 201

Headers
Content-Type: application/json
Body
{
    "data": {
        "aid": 1234,
        "id": "2120ae0818414cba840b68308710b98a",
        "name": "ML: Grow Customer Base",
        "label": "Predictive Model to grow customer base",
        "state": "complete",
        "source": "cf21ba3ceb194961b964358ee92ec4a9",
        "target": "e34563f98bc848b7abb17c4a0499968c",
        "type": "rf",
        "is_healthy": true,
        "is_active": true,
        "created": "2020-08-10T16:00:00.123456789-07:00",
        "updated": "2020-08-10T16:00:00.123456789-07:00",
        "config": {
            "collect": 5000,
            "use_scores": true,
            "use_content": true,
            "build_only": false,
            "auto_tune": false,
            "model_type": "rf",
            "re_run": true,
            "tune_model": true
        }
    }
}

ML Summary

/api/ml/{id}/summary

Get a summary of a ML model

GET

ML Model Summary Fetch

/api/ml/{id}/summary

Get a ML model summary

Additional atttributes from a ML model

fieldDataTypeDescription
features: kindstringThe 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: fieldtypestringField type is either numeric or categorical
features: namestringThe name of a field
features: importancenumberThe relative importance of a field in the model
features: correlationnumberCorrelation between specific field and target
features: impactobjectThe impact object details the Lift and shows the marginal effect of a feature on the predicted outcome of the model
msenumberMean-squared error value
rsqnumberR-squared value or coefficient of determination
false_negativenumberThe number of users in the source segment who are predicted to be in the target segment.
false_positivenumberThe number of users in the target segment who are not predicted to be in the target segment.
true_negativenumberThe number of users in the source segment who are not predicted to be in the target segment.
true_positivenumberThe number of users in the target segment who are predicted to be in the target segment.
success[]numberNumber of successful predictions for a given prediction value
failure[]numberNumber of failed predictions for a given prediction value
aucnumberArea under the ROC curve
thresholdnumberOptimal decision threshold to minimize false-positives and false-negatives
accuracynumberA value that represents the accuracy of the model; scale ranges from 0 (least accurate) to 10 (most accurate).
reachnumberA value that represents the number of source users that look like target users; scale ranges from 0 (low reach) to 10 (high reach).
model_healthnumberThe overall health of the model (i.e. "healthy", "unhealthy")
msgsnumberMessages 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.

# Curl example of getting a SegmentML model
curl -s -J -XGET "https://api.lytics.io/api/ml/abcdef123/summary" -H "Authorization: $LIOKEY"
Parameters
idstring (required)
Ex: abcdef123
ID of the ML model to retrieve

Response 200

Headers
Content-Type: application/json
Body
{
    "data": {
        "id": "abcdefg123456",
        "name": "My Custom ML Model",
        "summary": {
            "mse": 0.09,
            "rsq": 0.91,
            "auc": 0.90,
            "threshold": 0.55,
            "accuracy": 8,
            "reach": 4,
            "audience_similarity": 0.33,
            "health":  "healthy"
        },
        "features": [
            {
                "kind": "score",
                "type": "numeric",
                "name": "score_intensity",
                "importance": 47.123,
                "correlation": 0.11,
                "prevalance": {
                    "source": 0.84,
                    "target": 0.91
                },
                "impact": {
                    "lift": 0.22,
                    "threshold": 0.1,
                    "value": 40
                }
            },
            {
                "kind": "content",
                "type": "numeric",
                "name": "lytics_content::Baking",
                "importance": 12.123,
                "correlation": 0.29,
                "prevalance": {
                    "source": 0.14,
                    "target": 0.41
                },
                "impact": {
                    "lift": 0.02,
                    "threshold": 0.11,
                    "value": 0.71
                }
            }
        ]
    }
}