How Can We Help?

Predictions API

The Predictions API provides low-latency access to predictions made by the pipelines that you’ve built in your Cortex account. The API returns up-to-date results which can be used to power intelligent experiences in your digital products and business tools.

The following section will describe how to enable and send GET requests to the Predictions API. For clarity, the examples in this document assumes a Cortex account set up to make predictions about users. Note however that your account can be configured to predict for any type of entity tied to your event data (e.g. commerce inventory, media content, home listings, etc.).

Note that you will need to authenticate each request unless this requirement has been disabled for your account.

Enabling the API

In order to use the Predictions API, you must first build a recurring Future Events, Uplift, Classification, Regression, or Look Alike pipeline in Cortex. Any of these pipelines may be configured so that these predictions are accessible in real-time via the Predictions API (note: Recommendations pipelines are accessed separately via the Category Recommendations API). To enable the Predictions API, please contact your account manager or reach out to support@mparticle.com.

Get User Prediction

Given a unique entity ID (e.g. user_id) and a unique pipeline ID, returns up-to-date results generated by that pipeline for that entity. Results include:

  • Score: The predicted value for the entity (e.g. a user’s conversion probability from a Future Events pipeline)
  • Percentile: The percentile rank of the entity’s score relative to all scores (i.e. the percent of other users that received a lower prediction than this user). Note that ties are broken randomly so that no two users have the same percentile.

Each pipeline is identified by a unique ID that can be fetched using the Pipelines API or from Cortex.

Request

Method URL
GET /v1/items/<ENTITY_ID>/pipelines/<PIPELINE_ID>/predictions

Parameters

Param Required? Value Description
<ENTITY_ID> Yes string The unique ID of the entity (e.g. user) for which you’d like to return predictions.
<PIPELINE_ID> Yes string The unique ID of the pipeline from which you’d like to return a prediction. A pipeline_id is only valid if it corresponds to a recurring pipeline built in Cortex and enabled for the Predictions API.

Example Request

http://api-us.vidora.com/v1/items/<ENTITY_ID>/pipelines/<PIPELINE_ID>/predictions?api_key=<YOUR_KEY>&expires=2020-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

[ 
    { 
        "score": 0.81264,             # Prediction score from the pipeline
        "percentile": 0.93415         # Percentile of the prediction score from the pipeline
    }       
]

The above example shows a GET request to return results from pipeline <PIPELINE_ID> for user <ENTITY_ID>. The response indicates that the user’s prediction is 0.81264 (i.e. an 81% conversion probability for a Future Events pipeline), which is in the 93rd percentile as compared to all users’ predictions.

Response Codes

Response Description
200 OK The request was successful.
400 Bad Request The request was invalid, possibly due to malformed parameters.
401 Unauthorized The api_key and/or signature was invalid.
404 Not Found The id used in the request was not found or the request URI does not exist.
500 Internal Error There was a server side error, and we cannot serve the request at the current time.

Rate Limits

To ensure maximum performance, please limit your Predictions API requests to no more than 800 requests per second.

Related Links

Still have questions? Reach out to support@mparticle.com for more info!

Table of Contents