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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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

NameTypeDescription

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 /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

NameTypeDescription

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 /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

NameTypeDescription

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