Docs

Search Replay

Re-run a past search by ID with optional parameter overrides — for evaluation and regression testing.

The Replay API lets you re-execute a previous search, optionally with different parameters, and compare results. Useful for A/B evaluating ranking changes, regression-testing rerank model upgrades, or rebuilding a result set with stricter filters.

Request

bashPOST /v1/search/replay

Field	Type	Default	Description
`search_id`	string	--	ID returned by the original `/v1/buckets/{id}/search` call.
`override`	object	null	Optional. Fields applied to the rerun: `top_k`, `filter`, `min_score`, `mode`, `rerank`, `expand_neighbors`.
`include_original`	bool	false	Return the captured first-run results in the response.

Example

bashcurl -X POST https://api.schift.io/v1/search/replay \
  -H "Authorization: Bearer $SCHIFT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "search_id": "search_abc123",
    "override": {"min_score": 0.7, "rerank": true},
    "include_original": true
  }'

Response shape

json{
  "original": {
    "search_id": "search_abc123",
    "query": "soccer rules offside",
    "bucket_id": "bkt_xyz",
    "created_at": "2026-04-30T12:34:56Z",
    "result_count": 8,
    "results": [...]
  },
  "rerun": {
    "search_id": "search_def456",
    "results": [...],
    "diff": {
      "added": ["chunk-x"],
      "removed": ["chunk-y"],
      "shared": 5,
      "rank_correlation": 0.83
    }
  }
}

Diff metrics

added — IDs in the rerun that were not in the original.
removed — IDs in the original that dropped out.
shared — IDs present in both.
rank_correlation — Spearman correlation over shared IDs (1.0 = identical order, -1.0 = reversed). null when fewer than 2 shared IDs.

Limitation

The original full request payload (filter, top_k, etc.) is not yet persisted. An unmodified replay therefore runs with default search params, not bit-for-bit identical settings.