Recommender API
Detailed specification of the Recommender API
Prior to working with the Recommender API, please read through the API Getting Started page to learn about account creation, API keys, and other information on authentication. Each request requires that the appropriate authenication headers are included.
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
Name | Type | Description |
---|---|---|
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. |
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
Name | Type | Description |
---|---|---|
batch_id | str | A |
tags | str | list[str] | A set of one or more tags to search |
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
Name | Type | Description |
---|---|---|
batch_id | str | The |
tags | str | list[str] | One or more tags to identify which batches to delete. |
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
Name | Type | Description |
---|---|---|
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. |
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
Name | Type | Description |
---|---|---|
model_id* | str | The id provided or assigned to this model when training was initiated. |
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
Name | Type | Description |
---|---|---|
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". |
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
Name | Type | Description |
---|---|---|
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". |
Last updated