Skip to main content
Retrieve item recommendations given a user_id and/or session_id. Recommendations combine long‑term user signals with short‑term session context to return relevant items in real time. 
POST /v1/recommend

​
Request Body

​
user_id
string
required
Unique identifier for the user. Optional if session_id is provided. Please check with our team for your specific account configuration. In some cases session_id is disabled and only user_id is supported.
​
session_id
string
required
Unique identifier for the user’s current session. Optional if user_id is provided. Please check with our team if your account supports session_id.
​
item_ids
array
required
A list of item IDs to consider for recommendations.
​
model_id
string
required
The unique identifier of the model to use.Example: model_baseline-v1_4jbsb1qkzFJx3tQY7hB5Alternatively, older client versions can use the model_name field instead of model_id. Please confirm with our team if you are unsure.
​
limit
integer
The maximum number of items to return.
​
context
object
Optional session or user context for improved ranking. Can include fields like user_region, os_platform, device_type, referrer_source, or any custom context relevant to your use case.
Example Request
{
  "user_id": "2f396d29fb98",
  "item_ids": ["EC5792", "FC7890", "QW1234"],
  "limit": 10,
  "model_id": "model_baseline-v1_4jbsb1qkzFJx3tQY7hB5",
  "context": {
    "user_region": "US-CA",
    "os_platform": "iOS",
    "device_type": "mobile",
    "referrer_source": "email_campaign"
  }
}

curl -X POST https://api.sequen.com/v1/recommend \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "user_id": "2f396d29fb98",
    "item_ids": ["ST678VG", "QW1234"],
    "limit": 10,
    "model_id": "model_baseline-v1_4jbsb1qkzFJx3tQY7hB5",
    "context": {
      "user_region": "US-CA",
      "os_platform": "iOS",
      "device_type": "mobile",
      "referrer_source": "email_campaign"
    }
  }'

​
Response

{
  "rec_id": "rec_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "items": [
    {"id": "EC5792", "score": 0.95},
    {"id": "FC7890", "score": 0.87},
    {"id": "QW1234", "score": 0.78}
  ]
}
​
items
array
An array of recommended item objects sorted by rank (highest-ranked item first).Item Object Fields:
  • id (string, required): The unique identifier of the recommended item
  • score (float, required): The recommendation score assigned by the model
​
rec_id
string
A unique identifier for this specific set of recommendations.Example: rec_0ujsswThIGTUYm2K8FjOOfXtY1K
Example Response
{
  "rec_id": "rec_0ujsswThIGTUYm2K8FjOOfXtY1K",
  "items": [
    {"id": "EC5792", "score": 0.95},
    {"id": "FC7890", "score": 0.87},
    {"id": "QW1234", "score": 0.78},
    {"id": "AB4567", "score": 0.72},
    {"id": "XY9876", "score": 0.68}
  ]
}

​
Rate Limiting

Requests are rate‑limited. If you exceed your quota, the API returns 429 Too Many Requests.

​
Response Codes

Successful response with recommendations.
Malformed JSON or invalid parameters in the request body.
Missing or invalid Authorization header in request headers.
API key lacks permission to access this endpoint.
Request timed out. Please retry with exponential backoff.
Input failed validation. Check that required fields are present and correctly formatted.
Rate limit exceeded. Please retry with exponential backoff.
Temporary server issue. Please retry with exponential backoff.