Predictions API

The Predictions API provides low-latency access to predictions made by any pipeline in your Cortex account. The Predictions API returns up-to-date predictions directly to your digital products and business tools, enabling you to build automated mechanisms which act on these predictions in intelligent ways.

The following section will describe how to enable and send GET requests to the Predictions API. To frame these requests in real terms, this document assumes a Cortex account configured to make predictions about users. Note however that your Cortex account can be configured to predict for any type of object tied to your event data (e.g. commerce items, media content, home listings, etc.).

If signatures are enabled for your account, you’ll need to append a signature to each request.

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 user ID, returns an array of up-to-date predictions for every API-configured pipeline that has generated a prediction for that user (or any other type of object).

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

Request

Method URL
GET /v1/objects/<OBJECT_ID>/predictions

 

Parameters

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

 

Example Request

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

Example Response

[
    { "vnscuql29utc6ebl": 0.81264 },
    { "pzy0xdbwszpgt2jt": 0.68093 },
    { "1hmb6sffiqdgm8b9": 0.39385 }
]

The above example request makes a signed call to the Predictions API to retrieve prediction scores for each of three pipelines that have processed object <OBJECT_ID>.

Get User Prediction

Given a unique user ID and a unique pipeline id, returns an up-to-date prediction generated by the pipeline for the user (or any other type of object).

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

Request

Method URL
GET /v1/objects/<OBJECT_ID>/predictions/<PIPELINE_ID>

 

Parameters

Param Required? Value Description
<OBJECT_ID> Yes string The unique id of the object (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/objects/<OBJECT_ID>/predictions/<PIPELINE_ID>?api_key=<YOUR_KEY>&expires=2020-0101T00%3A00&signature=<YOUR_SIGNATURE>

Example Response

{ "score": 0.79188 }

The above example request makes a signed call to the Models API to retrieve a prediction score from pipeline <PIPELINE_ID> for object <OBJECT_ID>.

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.

 

Related Links

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

Table of Contents