Skip to the content
  1. API reference
  2. Recommendations

Send listening events

POST/public/recommendations/events
CoreAuthBasic

Sends what your listeners did: play, complete, skip, like, dislike. At most 1,000 events and 1 MiB in one call. The events build each listener's taste for GET /public/recommendations/users/{userId}/recommendations and POST /public/recommendations/next. An event more than 5 minutes in the future or older than 400 days is rejected and listed with its index; the rest are stored. An ISRC we do not know yet is stored too. Each accepted event counts on your usage. Needs Client Secret authentication.

Request body

application/json · required

events
object[]
required
events[].userId
string
requiredYour own id of the listener.
events[].isrc
string
required
events[].type
string
requiredOne of: play, skip, like, dislike, complete
events[].at
date-time
requiredWhen it happened, ISO 8601.
events[].msPlayed
number
How long the track played. A play under 30 s counts half.Default: 0

Response

202application/json · RecommendationEventsResponseStored.
accepted
number
required
rejected
object[]
required
rejected[].index
number
requiredThe position of the event in events, from 0.
rejected[].reason
string
requiredOne of: in_future, too_old
Example answer
{
  "accepted": 998,
  "rejected": [
    {
      "index": 0,
      "reason": "in_future"
    }
  ]
}

Errors

400

More than 1,000 events, or an event with a missing or malformed field.

401

No valid credential.

403

The request does not use Client Secret authentication.

413

payload_too_large: the body is larger than 1 MiB.

429

Your account sent more calls this minute than its rate limit allows.