Skip to main content
POST
/
v1
/
events
curl --request POST \
  --url https://api.neuronsearchlab.com/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "usr_abc123",
  "item_id": "itm_7f3a2c9e",
  "context_id": "101",
  "type": "purchase",
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "occurred_at": 1777478400,
  "purchase": {
    "amount": 4999,
    "currency": "usd"
  },
  "metadata": {
    "surface": "home_feed"
  }
}
'
{
  "object": "list",
  "data": [
    {
      "id": "evt_12345",
      "object": "event",
      "user_id": "usr_abc123",
      "item_id": "itm_7f3a2c9e",
      "type": "purchase",
      "purchase": {
        "amount": 4999,
        "currency": "usd"
      },
      "session_id": null,
      "request_id": null,
      "context_id": "101",
      "placement": null,
      "metadata": {
        "surface": "home_feed",
        "context_id": "101",
        "purchase": {
          "amount": 4999,
          "currency": "usd"
        }
      },
      "occurred_at": 1777478400,
      "created": 1777478405
    }
  ],
  "has_more": false,
  "url": "/v1/events",
  "inserted": 1,
  "processed": 1,
  "session": {
    "with_session_id": 0,
    "with_request_id": 0
  },
  "embedding_refresh": {
    "users_in_batch": 1,
    "enqueued": true,
    "mode": "async",
    "min_seconds": 30
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.neuronsearchlab.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Description

Records user behavior that powers personalization, attribution, analytics, and model training. Events use a type field plus a type-specific object so new event shapes can be added without changing shared fields. Common event types are impression, view, click, like, purchase, and conversion. Your console event definitions decide which types are valid for your tenant.

​
Request

POST /v1/events

{
  "user_id": "usr_abc123",
  "item_id": "itm_7f3a2c9e",
  "context_id": "101",
  "type": "purchase",
  "occurred_at": 1777478400,
  "purchase": {
    "amount": 4999,
    "currency": "usd"
  },
  "metadata": {
    "surface": "home_feed"
  }
}
FieldTypeRequiredDescription
user_idstringyesEnd-user identifier.
item_idstringyesPrefixed item ID such as itm_7f3a2c9e.
context_idstringnoOptional context identifier for analytics and attribution. Use the same context ID convention as your recommendation request, for example 101.
typestringyesEvent type configured in the console.
session_idstringnoSession identifier for attribution and analytics.
request_idstringnoRecommendation request ID returned by GET /v1/recommendations.
placementstringnoSurface or placement where the event occurred.
occurred_atintegernoUnix timestamp for when the action happened. Defaults to ingestion time.
<type>objectnoType-specific payload. Include {} when there are no type-specific fields.
metadataobjectnoAdditional event context.
Legacy aliases userId, itemId, eventType, event_type, eventId, event_id, contextId, sessionId, requestId, client_ts, clientTs, occurredAt, and timestamp are still accepted. Event batches are capped at 200 events per request by default.

​
Response

{
  "object": "list",
  "data": [
    {
      "id": "evt_12345",
      "object": "event",
      "user_id": "usr_abc123",
      "item_id": "itm_7f3a2c9e",
      "type": "purchase",
      "purchase": {
        "amount": 4999,
        "currency": "usd"
      },
      "session_id": null,
      "request_id": null,
      "context_id": "101",
      "placement": null,
      "metadata": {
        "surface": "home_feed",
        "context_id": "101",
        "purchase": {
          "amount": 4999,
          "currency": "usd"
        }
      },
      "occurred_at": 1777478400,
      "created": 1777478405
    }
  ],
  "has_more": false,
  "url": "/v1/events",
  "inserted": 1,
  "processed": 1,
  "session": {
    "with_session_id": 0,
    "with_request_id": 0
  },
  "embedding_refresh": {
    "users_in_batch": 1,
    "enqueued": true,
    "mode": "async",
    "min_seconds": 30
  }
}
The response also returns ingestion stats (inserted, processed, session) and an embedding_refresh block describing the async user-embedding refresh job that was enqueued for the affected users.

​
Errors

StatusScenario
400Missing required fields, invalid JSON, unknown item, or unknown event type
401Missing or invalid Bearer token
403Token does not include neuronsearchlab-api/write

Authorizations

​
Authorization
string
header
required

The access token received from the authorization server in the OAuth 2.0 flow.

Body

application/json

At least one user ID alias, one item ID alias, and one event type alias are required. Type-specific payloads are accepted as additional object properties named after the event type.

​
user_id
string

End-user identifier.

Example:

"usr_abc123"

​
userId
string

CamelCase alias for user_id.

​
item_id
string

Public item ID.

Pattern: ^itm_[A-Za-z0-9][A-Za-z0-9_-]{2,}$
Example:

"itm_7f3a2c9e"

​
itemId
string

CamelCase alias for item_id.

Pattern: ^itm_[A-Za-z0-9][A-Za-z0-9_-]{2,}$
​
type
string

Tenant-configured event type.

Example:

"purchase"

​
event_type
string

Snake-case alias for type.

​
eventType
string

CamelCase alias for type.

​
event_id

Legacy alias for event type.

​
eventId

CamelCase legacy alias for event type.

​
session_id
string

Optional session identifier.

​
sessionId
string

CamelCase alias for session_id.

​
request_id
string<uuid>

Recommendation request ID to attribute this event to.

​
requestId
string<uuid>

CamelCase alias for request_id.

​
context_id
string

Optional context identifier for analytics and attribution. Use the same context ID convention as the recommendation request.

Example:

"101"

​
contextId
string

CamelCase alias for context_id.

Example:

"101"

​
placement
string

Surface or placement where the event happened.

Example:

"home_feed"

​
metadata
object

Arbitrary JSON object used for filtering, ranking, and debugging.

Example:
{
  "category": "electronics",
  "brand": "Acme",
  "price": 10999,
  "currency": "usd"
}
​
occurred_at

Event occurrence timestamp. Numeric values below 1e12 are interpreted as Unix seconds.

Example:

1777478400

​
occurredAt

CamelCase alias for occurred_at.

​
timestamp

Legacy timestamp alias.

​
client_ts

Legacy client timestamp alias.

​
clientTs

CamelCase alias for client_ts.

Response

Inserted events

​
object
enum<string>
required
Available options:
list
​
data
object[]
required
​
has_more
boolean
required
​
url
string
required
​
inserted
integer
required
Required range: x >= 0
​
processed
integer
required
Required range: x >= 0
​
session
object
required
​
embedding_refresh
object
required
​
next_cursor
string | null