Recommender API
Detailed specification of the Recommender API
Importing data
Upload batch of item or interaction data
POST /v1/recommender/data_batch
Upload a batch of items or interactions for processing. Multiple batches can be uploaded through repeated API calls if there is a large volume of data, or if it is streaming in over time. Utilize the tags parameter to identify batches and group them together for downstream training. The uploaded data files must be in .csv format and must contain column names required by the entity and interaction table formats, which can be found here.
Request Body
tags
str | list[str]
A list of tags associated with this dataset, which can be used to later query, delete, or update this batch
files*
bytes
A file to upload in this batch. Each file must be in .csv format and contain either entity or interaction data in the required format.
{
[
"batch_id": "string",
"timestamp": "2022-08-23T21:22:09.547Z",
"tags": [
"string"
],
"entity_count": 0,
"interaction_count": 0
]
}Get info about uploaded data batches
GET /v1/recommender/data_batch
Gets metadata about one or more data batches that match the specified query parameters. Data batches can be queried by their batch_id or by a set of tags. If tags are specified, all batches matching all tags have their metadata returned. Note that this request does not return the data itself, only the batch metadata.
Query Parameters
batch_id
str
A batch_id returned from uploading a data batch through a POST operation
tags
str | list[str]
A set of one or more tags to search
{
[
"batch_id": "string",
"timestamp": "2022-08-23T21:22:09.547Z",
"tags": [
"string"
],
"entity_count": 0,
"interaction_count": 0
]
}Delete a batch of data
DELETE /v1/recommender/data_batch
Delete one or more batches matching the specified batch_id and/or tags. If tags are specified, all batches that match all tags will be deleted.
Query Parameters
batch_id
str
The batch_id returned from creating the batch.
tags
str | list[str]
One or more tags to identify which batches to delete.
{
"batch_ids": ["string"]
}Training the recommender model
Initiate recommender model training
POST /v1/recommender/train
Starts training a recommender model using the specified data batches as inputs. Training may take minutes to hours depending on the size of the dataset. This API request will return immediately and provide metadata about the training process so it can be tracked with the /status request. Additionally, a callback_url can be provided to notify listeners when the training is complete.
Request Body
model_id
str
A unique ID for this model. If a model with this ID already exists, this model will overwrite that one when training completes.
maximum_interaction_age_days
int
Limits the age of interactions used when training the model. Can be used to only consider fresh data from the datasets.
data_tags
str | list[str]
Limits the training datasets to only include those that match one or more of these tags.
callback_url
str
A URL to trigger when training completes. The URL is triggered regardless of whether the training is successful or not.
{
"model_id": "string",
"start_timestamp": "2022-08-26T01:30:13.523Z",
"end_timestamp": "2022-08-26T01:30:13.523Z",
"status": "string",
"message": "string",
"progress": 0,
"data_batch_ids": [
"string"
],
"data_filters": {}
}Query the status of a previously started training run
GET /v1/recommender/{model_id}/status
Queries the status of a previously started training run.
Query Parameters
model_id*
str
The id provided or assigned to this model when training was initiated.
{
"model_id": "string",
"start_timestamp": "2022-08-26T01:30:13.523Z",
"end_timestamp": "2022-08-26T01:30:13.523Z",
"status": "string",
"message": "string",
"progress": 0,
"data_batch_ids": [
"string"
],
"data_filters": {}
}Querying recommendation results
Get recommended items from the trained model
GET /v1/recommender/related_items
For a given set of entities or entity types, it returns the relevant recommendations. By default it will return batch recommendations in CSV format, though you can also query for specific entities or get results in JSON format.
Query Parameters
model_id*
str
The name of the model to query.
entity_id
str
If provided, will limit the recommendations to this list of comma-separated entities.
max_recommendations
int
The maximum number of recommendations to return per entity; defaults to 100.
threshold
float
A threshold for the minimum matching score, between 0.0-1.0. Defaults to 0.0 (i.e., no threshold).
entity_type
str
If provided, will limit the recommendations to entities have types in this list of comma-separated values.
output_format
str
Can be "csv" or "json", which will control the output format. Defaults to "csv".
{
// Response
}Get trending items from the trained model
GET /v1/recommender/trending_items
For a given set of entity types, get out a list of trending items. By default it will return batched results in CSV format for convenience.
Query Parameters
model_id
str
The name of the model to query.
entity_type
str
If provided, will limit the trend recommendations to entities have types in this list of comma-separated values.
max_recommendations
int
The maximum number of recommendations to return per entity; defaults to 100.
threshold
float
A threshold for the minimum matching score, between 0.0-1.0. Defaults to 0.0 (i.e., no threshold).
output_format
str
Can be "csv" or "json", which will control the output format. Defaults to "csv".
{
// Response
}Last updated