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;
};

Every search response carries a queryID unless the request set clickAnalytics: false, in which case it is null — see Search. Without a queryID, there is nothing to attribute the click back to, so there is no click event to send.

Treat queryID as an opaque string. It stays valid for one hour after the search; a click sent later still gets a 204, but it isn't counted.

A queryID belongs to the account that ran the search. A click sent with a key from a different account still gets a 204, but it isn't counted. Each queryID counts once for each objectID, so sending the same click again changes nothing. objectID may be at most 512 characters, and the body at most 16,384 bytes; a larger body is refused with 413 and request_too_large.

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.