Submit events

curl --request POST \
  --url https://api.neuronsearchlab.com/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user-abc123",
  "item_id": 3187,
  "context_id": 101,
  "event_id": 42,
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "occurred_at": 1777478400,
  "purchase": {
    "amount": 4999,
    "currency": "usd"
  },
  "metadata": {
    "surface": "home_feed"
  }
}
'

{
  "object": "list",
  "data": [
    {
      "id": 12345,
      "object": "event",
      "user_id": "user-abc123",
      "item_id": 3187,
      "event_id": 42,
      "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
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Validation error",
    "details": {
      "fieldErrors": {
        "name": [
          "Required"
        ]
      }
    }
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized_no_client_id_in_jwt",
    "message": "Unauthorized: No client ID in JWT"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

POST

events

curl --request POST \
  --url https://api.neuronsearchlab.com/v1/events \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "user_id": "user-abc123",
  "item_id": 3187,
  "context_id": 101,
  "event_id": 42,
  "request_id": "c7f0d2bb-56b1-4ca7-8f09-84d8e4ed02b4",
  "occurred_at": 1777478400,
  "purchase": {
    "amount": 4999,
    "currency": "usd"
  },
  "metadata": {
    "surface": "home_feed"
  }
}
'

{
  "object": "list",
  "data": [
    {
      "id": 12345,
      "object": "event",
      "user_id": "user-abc123",
      "item_id": 3187,
      "event_id": 42,
      "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
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Validation error",
    "details": {
      "fieldErrors": {
        "name": [
          "Required"
        ]
      }
    }
  }
}

{
  "error": {
    "type": "authentication_error",
    "code": "unauthorized_no_client_id_in_jwt",
    "message": "Unauthorized: No client ID in JWT"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

{
  "error": {
    "type": "invalid_request_error",
    "code": "<string>",
    "message": "<string>",
    "details": "<unknown>",
    "request_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  }
}

Description

Records user behavior that powers personalization, attribution, analytics, and model training. event_id must be the non-zero integer shown for an event in your dashboard. Event names such as "click" are display labels and are not accepted as identifiers.

Request

POST /v1/events

{
  "user_id": "user-abc123",
  "item_id": 3187,
  "context_id": 101,
  "event_id": 42,
  "occurred_at": 1777478400,
  "metadata": {
    "surface": "home_feed",
    "amount": 4999,
    "currency": "usd"
  }
}

Field	Type	Required	Description
`user_id`	string	yes	End-user identifier.
`item_id`	integer	yes	Item ID returned by NSL ingestion, such as `3187`.
`context_id`	integer	no	Context ID generated when the context is created in the dashboard.
`event_id`	integer	yes	Event ID generated when the event is created in dashboard Event configuration.
`session_id`	string	no	Session identifier for attribution and analytics.
`request_id`	string	no	Recommendation request ID returned by `GET /v1/recommendations`.
`placement`	string	no	Surface or placement where the event occurred.
`occurred_at`	integer	no	Unix timestamp for when the action happened. Defaults to ingestion time.
`metadata`	object	no	Additional event context.

Camel-case aliases userId, itemId, eventId, contextId, sessionId, and requestId remain available, but all identifier aliases carry the same integer values. Event batches are capped at 200 events per request by default.

Response

{
  "object": "list",
  "data": [
    {
      "id": 12345,
      "object": "event",
      "user_id": "user-abc123",
      "item_id": 3187,
      "event_id": 42,
      "session_id": null,
      "request_id": null,
      "context_id": 101,
      "placement": null,
      "metadata": {
        "surface": "home_feed",
        "context_id": 101
      },
      "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

Status	Scenario
`400`	Missing required fields, invalid JSON, unknown item, or unknown event type
`401`	Missing or invalid Bearer token
`403`	Token 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

object
object[]

A user ID, a non-zero dashboard event_id, and a positive NSL-generated item_id are required. context_id is also a positive NSL-generated integer when supplied.

user_id

string

End-user identifier.

Example:

"user-abc123"

userId

string

CamelCase alias for user_id.

item_id

integer

Item ID returned by NSL ingestion.

Required range: x >= 1

Example:

3187

itemId

integer

CamelCase alias for item_id.

Required range: x >= 1

event_id

integer

Non-zero event ID shown in dashboard Event configuration.

eventId

integer

CamelCase alias for event_id.

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

integer

Optional context ID created in the dashboard.

Required range: x >= 1

Example:

101

contextId

integer

CamelCase alias for context_id.

Required range: x >= 1

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

Show child attributes

has_more

boolean

required

url

string

required

inserted

integer

required

Required range: x >= 0

processed

integer

required

Required range: x >= 0

session

object

required

Show child attributes

embedding_refresh

object

required

Show child attributes

next_cursor

string | null

Overview

Authentication

Items

Events

Recommendations

Search

Description

Request

Response

Errors

Authorizations

Body

Response

​Description

​Request

​Response

​Errors

Authorizations

Body

Response

Description

Request

Response

Errors