# Send listening events
URL: https://musicapi.com/docs/reference/recommendations-send-events.md

`POST https://api.musicapi.com/public/recommendations/events`

Section: Recommendations.
Product: MusicAPI Core.
Auth: Basic (any one of them). Use Basic with your Client ID and Client Secret from your server only.

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.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `events` | object[] | yes |  |
| `events[].userId` | string | yes | Your own id of the listener. |
| `events[].isrc` | string | yes |  |
| `events[].type` | string | yes | One of: play, skip, like, dislike, complete. |
| `events[].at` | date-time | yes | When it happened, ISO 8601. |
| `events[].msPlayed` | number | no | How long the track played. A play under 30 s counts half. |

## Response 202

Stored.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `accepted` | number | yes |  |
| `rejected` | object[] | yes |  |
| `rejected[].index` | number | yes | The position of the event in `events`, from 0. |
| `rejected[].reason` | string | yes | One of: in_future, too_old. |

```json
{
  "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.

## Example

```bash
curl -X POST "https://api.musicapi.com/public/recommendations/events" \
  -u "$MUSICAPI_CLIENT_ID:$MUSICAPI_CLIENT_SECRET" \
  -H "Content-Type: application/json" \
  -d '{"events":[{"userId":"listener-8812","isrc":"USRC17607839","type":"play","at":"2026-10-16T09:41:07.000Z","msPlayed":0}]}'
```
