Report user event API

Use the POST /v1/stats/{index_public_key} endpoint to report user search and click events to AddSearch analytics. This helps track user interactions and improve search relevance.

Endpoint

POST /v1/stats/{index_public_key}

Replace {index_public_key} with your AddSearch index's public key.

Event types

You can report two types of events:

• Search event: when a user performs a search query
• Click event: when a user clicks a search result

Search event payload

{
  "action": "search",
  "session": "session_name",
  "keyword": "test query",
  "numberOfResults": 4,
  "tag": "optional_tag"
}

Search event parameters

Parameter	Description	Type	Notes
action	Type of user action	string	Must be exactly "search"
session	Unique user search session identifier	string	Up to 32 characters, used to group related actions
keyword	Search keywords entered by the user	string	Multiple keywords separated by spaces
numberOfResults	Number of results returned for this query	integer	Zero indicates a "No hit" event in the analytics dashboard
tag	Optional tag to filter analytics in dashboard	string	Up to 50 characters; see analytics tags

Click event payload

{
  "action": "click",
  "session": "session_name",
  "keyword": "test query",
  "docid": "abc123",
  "position": 1,
  "tag": "optional_tag"
}

Click event parameters

Parameter	Description	Type	Notes
action	Type of user action	string	Must be exactly "click"
session	Unique user search session identifier	string	Up to 32 characters
keyword	Search keywords associated with the click	string	Multiple keywords separated by spaces
docid	ID of the clicked document	string	MD5 hash of the document's full URL including protocol and query parameters. Max length 32 characters.
position	Position of the clicked item in search results	integer	Starts at 1
tag	Optional tag to filter analytics in dashboard	string	Up to 50 characters; see analytics tags

Request details

• Content-Type: application/json
• Returns: HTTP 200 OK on success

Important notes

• Searches performed through the search API endpoint are automatically reported.
• For custom search UI implementations, set the collectAnalytics parameter to false in the search API to avoid duplicate events.
• Instead, report search and click events explicitly using this API endpoint to ensure accurate analytics and ranking adjustments based on user behavior.

See also

• Analytics tags
• Search API endpoint