---
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`

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 — ID of the retriever execution that generated these results. HIGHLY RECOMMENDED for analytics.
  - `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` — Validation Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/mixpeek/apis/mixpeek-api.md) · [All operations](https://skmtc.net/mixpeek/apis/mixpeek-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mixpeek/mixpeek-api/revisions/220a3b263fda/schema)