Skip to main content

For AI agents: a Markdown version of this page is at https://docs.snowplow.io/docs/signals/applications/predictive-attributes.md. The index of all documentation pages is at https://docs.snowplow.io/llms.txt, and the index for this section is at https://docs.snowplow.io/docs/signals/llms.txt.

Retrieve predictive attribute scores in your application

Public preview

Predictive attributes are in public preview. Their configuration, API, and behavior may change in ways that aren't backward compatible before they're generally available.

Once a predictive attribute is published, request a score in your application to decide how to treat a session, for example whether to show an offer. Signals calculates the score when you request it, from the most recent values of the model's input attributes. Your application requests the score and decides what to do with it. Start by connecting to Signals.

Get the identifiers​

A predictive attribute can use input attributes with different attribute keys, for example session-level attributes keyed on domain_sessionid and user-level attributes keyed on domain_userid. To score it, pass one identifier for each attribute key its inputs use. An empty identifier counts as missing, and Signals ignores identifiers for other keys. An identifier Signals hasn't seen before still gets a score, calculated from empty attribute values.

Requests to Signals need credentials, so request scores from your server. In the browser, read the identifiers with the tracker's getDomainSessionId and getDomainUserId methods, then send them to your server, for example as request parameters.

Retrieve a score​

Request a score by the predictive attribute's name. Signals uses the published version and training.

Use get_predictive_attribute_score() to score a predictive attribute.

python
# The Signals connection object has been created as sp_signals

result = sp_signals.get_predictive_attribute_score(
name="purchase_propensity",
identifiers={
"domain_sessionid": "8c9104e3-c300-4b20-82f2-93b7fa0b8feb",
"domain_userid": "218e8926-3858-431d-b2ed-66da03a1cbe5",
},
)
print(result.score)
ArgumentDescriptionTypeRequired?
nameThe name of the predictive attributestring✅
identifiersOne identifier for each attribute key used by the input attributesdict[str, str]✅

Read the response​

The response contains the score and the version of the model that produced it:

json
{
"name": "purchase_propensity",
"version": 2,
"minor_version": 1,
"score": 0.42
}

The table below describes each field in the response.

FieldDescriptionType
nameThe name of the predictive attributestring
versionThe published version of the predictive attributeinteger
minor_versionThe training of that version whose model produced the scoreinteger
scoreHow likely the session is to reach the goal, between 0 and 1number

Interpret the score​

A higher score means the model considers the goal more likely. Use the score to rank sessions and set a threshold to act above, not as an exact probability. Signals corrects scores for the sampling it uses in training, so they're on the scale of your real goal rate, but they aren't guaranteed to be calibrated. A session scored 0.6 is more likely to reach the goal than one scored 0.3, but not necessarily 60% likely. Choose thresholds by looking at the scores your sessions receive, and revisit them each time you publish a new training, because a new model can shift the range of scores.

Signals scores a session whatever state it's in. Scores are less reliable for states that training doesn't cover, such as a very short session, or a session that has already reached the goal.

Handle errors​

The endpoint returns these error codes:

StatusCause
400The name is missing or invalid, a parameter appears more than once, or there's no identifier for one of the attribute keys the inputs use
401The token is missing, invalid, or expired
404No version of the predictive attribute is published
500An unexpected error, for example an input attribute group is no longer published
503Scoring is temporarily unavailable, for example while the model is being published or loaded. Retry after a few seconds
504Reading the input attributes took longer than the request timeout

The SDKs raise these as a SignalsAPIError that carries the status code.

Signals free tier and Snowplow CDI

New to Snowplow: the Signals free tier is a hosted environment, with event collection included, capped at 5 million events a month, with no end date or credit card. Snowplow runs it on AWS, in the US or the EU depending on the region you sign up from.

Already run Snowplow CDI: Signals reads events from your existing pipeline, and is deployed in the AWS region you choose. See Set up Signals.

Was this page helpful?