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

# Track Interaction Batch

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

## Request

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

Track multiple interactions in a single request (batching).

More efficient than sending individual interaction requests.
Use this for batching viewport visibility, bulk actions, etc.

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

**Recommended Headers:**
- `X-Session-ID`: Applied to all interactions in the batch

**Limits:**
- Maximum 100 interactions per batch

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

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

- PublicInteractionBatchRequest: Request to track multiple interactions in batch.
  - `interactions` PublicInteractionRequest[], required: List of interactions to track (max 100 per batch)
    - `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 `interactions/items/interaction_type/items/`
  - added the new `download` enum value to the request property `interactions/items/interaction_type/items/`
  - added the new `play` enum value to the request property `interactions/items/interaction_type/items/`
  - added the new `rating` enum value to the request property `interactions/items/interaction_type/items/`
  - …1 more

[Operation history](https://skmtc.dev/mixpeek/apis/mixpeek-api/changes/v1/public/retrievers/:public_name/interactions/batch/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)