Click events

POST /1/events/click

Requires the same key that ran the search (or a scoped token with matching claims).

Request

type ClickEvent = {
	queryID: string;
	objectID: string;
	position: number;
};

queryID only exists when the originating search was sent with clickAnalytics: true — see Search. Without a queryID, there is nothing to attribute the click back to, so there is no click event to send.

Example

curl -X POST https://api.usesuo.com/1/events/click \
  -H "x-suo-key: suo_search_YOUR_KEY" \
  -H "content-type: application/json" \
  -d '{ "queryID": "q_8f2c1a94", "objectID": "page-482", "position": 3 }'

What this powers

Click-through rate and "top clicked" in Reading analytics, and nothing else — a click event never affects ranking directly. suo's non-goals for v1 explicitly exclude learning-to-rank: clicks are recorded for you to read, not fed back into the ranking cascade automatically.

The widget sends this for you

If you are using <suo-search>, click events are sent automatically for every result the visitor opens — you only need to call this endpoint yourself if you built a custom results UI on top of the headless client.