Predictions API

The Predictions API provides low-latency access to predictions made by any pipeline 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 item 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 pipeline in Cortex. Any pipeline that is set up to generate predictions on an ongoing basis may be configured so that these predictions are accessible in real-time via the Predictions API. To enable the API, please contact your account manager or reach out to support@vidora.com.

List User Predictions

Given a unique item ID (e.g. user_id), returns an array of up-to-date results for every API-configured pipeline that has generated a prediction for that item.

For a Future Events, Look Alike, Classification, or Regression pipeline, results include:

  • Score: The predicted value for the item (e.g. a user’s conversion probability from a Future Events pipeline)
  • Percentile: The percentile rank of the item’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.

For a Recommendations pipeline, results include the following data for at most the top 25 recommended items for each user:

  • ID: An identifier for the item that is being recommended. 
  • Score: A score indicating Cortex’s certainty that the user will interact with that item next. Scores across all item values sum to 1 for each user.

In the response, 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/<ITEM_ID>/predictions

 

Parameters

Param Required? Value Description
<ITEM_ID> Yes string The unique ID of the item (e.g. user) for which you’d like to return predictions.

 

Example Request

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

Example Response

{
    "vnscuql29utc6ebl":                                      # Unique ID of the pipeline
        [{ "score": 0.81264, "percentile": 0.93415 }],       # Pipeline results for the user
    "pzy0xdbwszpgt2jt": 
        [{ "score": 0.68093, "percentile": 0.41247 }]
}

The above example shows a GET request to return results from all pipelines for the user identified by <ITEM_ID>. The response indicates that there are two API-configured pipelines that have processed the user. For the first pipeline, 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.

Get User Prediction

Given a unique item ID (e.g. user_id) and a unique pipeline ID, returns up-to-date results generated by that pipeline for that item. For a Future Events, Look Alike, Classification, or Regression pipeline, results include:

  • Score: The predicted value for the item (e.g. a user’s conversion probability from a Future Events pipeline)
  • Percentile: The percentile rank of the item’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.

For a Recommendations pipeline, results include the following data for at most the top 25 recommended items for each user:

  • ID: An identifier for the item that is being recommended. 
  • Score: A score indicating Cortex’s certainty that the user will interact with that item next. Scores across all item values sum to 1 for each user.

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/<ITEM_ID>/pipelines/<PIPELINE_ID>/predictions

 

Parameters

Param Required? Value Description
<ITEM_ID> Yes string The unique ID of the item (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.vidora.com/v1/items/<ITEM_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 <ITEM_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@vidora.com for more info!

Table of Contents