---
title: "Track Interaction"
method: POST
path: "/v1/public/retrievers/{public_name}/interactions"
tags: ["Public Retriever API"]
---

# Track Interaction

`POST /v1/public/retrievers/{public_name}/interactions`

## Request

- Base URL: `https://api.mixpeek.com`
- URL: `https://api.mixpeek.com/v1/public/retrievers/{public_name}/interactions`
- Auth: none required

Track user interaction with search results.

Records user engagement (clicks, views, etc.) for analytics and
potential search optimization (Learning to Rank).

**Authentication:**
- API key is OPTIONAL (same as execute endpoint)
- Password NOT required (tracking should work even without auth)

**Recommended Headers:**
- `X-Session-ID`: Session identifier for tracking user journey

**Interaction Types:**
- `VIEW`: Result was visible in viewport
- `CLICK`: User clicked on result
- `POSITIVE_FEEDBACK`: User explicitly liked result
- `NEGATIVE_FEEDBACK`: User explicitly disliked result
- `PURCHASE`: User purchased/converted
- `ADD_TO_CART`: User added to cart
- `WISHLIST`: User added to wishlist
- `LONG_VIEW`: User spent significant time viewing
- `SHARE`: User shared result
- `BOOKMARK`: User bookmarked result

**Example:**
```bash
curl -X POST "https://api.mixpeek.com/v1/public/retrievers/video-search/interactions" \
  -H "X-Session-ID: sess_xyz..." \
  -H "Content-Type: application/json" \
  -d '{
    "document_id": "doc_123",
    "interaction_type": ["CLICK"],
    "position": 2,
    "execution_id": "exec_abc",
    "query_snapshot": {"query": "red car"}
  }'
```

## Path parameters

- `public_name` string, required: Public name of the published retriever

## Headers

- `X-Session-ID` string, nullable
- `X-Public-API-Key` string, nullable

## Request body

- PublicInteractionRequest: Request to track a single interaction from public retriever. Simplified wrapper around SearchInteraction for public API use.
  - `document_id` string, required: ID of the document that was interacted with (from search results)
  - `interaction_type` InteractionType[], required: Type(s) of interaction that occurred
  - `position` integer, required: Position in search results (0-indexed)
  - `execution_id` string, nullable: REQUIRED. ID of the retriever execution that generated these results, as returned by the search. An interaction without it is refused (422).
  - `query_snapshot` object, nullable: Snapshot of the query that generated these results. HIGHLY RECOMMENDED for training optimization.
  - `document_score` number, nullable: Initial retrieval score of this document
  - `result_set_size` integer, nullable: Total number of results shown
  - `session_id` string, nullable: Session identifier for tracking user journey
  - `metadata` object, nullable: Additional context about the interaction

## Response `200`

Successful Response

- unknown

## Other responses

- `400`: Bad Request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Not Found
- `422`: Unprocessable Entity
- `429`: Too Many Requests
- `500`: Internal Server Error
- `503`: Service Unavailable

## Changes

- **2026-10-09** `61a175e8eb9a`: 1 warning, 5 info
  - removed the optional property `detail` from the response with the `422` status
  - added the non-success response with the status `429`
  - added the non-success response with the status `503`
  - added the optional property `success` to the response with the `422` status
  - …2 more
- **2026-08-23** `5307993e44d3`: 5 info
  - added the new `add_to_project` enum value to the request property `interaction_type/items/`
  - added the new `download` enum value to the request property `interaction_type/items/`
  - added the new `play` enum value to the request property `interaction_type/items/`
  - added the new `rating` enum value to the request property `interaction_type/items/`
  - …1 more

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/public/retrievers/:public_name/interactions/post.md)

---

[API](https://skmtc.dev/mixpeek/apis/mixpeek-api.md) - [All operations](https://skmtc.dev/mixpeek/apis/mixpeek-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mixpeek/apis/mixpeek-api/revisions/790bc16455f6?raw)