Search Replay

Show:

Search Replay re-runs a previous search using the search_id returned by an earlier captured search call. You can override individual search parameters for evaluation, regression testing, or A/B comparisons of ranking changes.

Note: Replay is available for searches that produce a search session, such as bucket searches. The endpoint does not yet replay federated memory searches as a single logical query.

POST /v1/search/replay

Re-runs a past search by search_id.

Request body

Field	Type	Required	Default	Description
`search_id`	string	yes	—	ID returned by a captured search call. Maximum 128 characters.
`override`	object	no	`null`	Optional parameter overrides applied to the rerun. See Override fields.
`include_original`	boolean	no	`false`	Return the captured first-run results in the response.

Override fields

Field	Type	Description
`top_k`	integer (1–1000)	Number of results to return.
`filter`	object	Search filter object.
`min_score`	number (0.0–1.0)	Minimum result score.
`mode`	string	Search mode override.
`rerank`	boolean	Whether to apply reranking.
`expand_neighbors`	object	Neighbor expansion parameters.

Example request

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

{
  "original": {
    "search_id": "search_abc123",
    "query": "soccer rules offside",
    "bucket_id": "bkt_xyz",
    "created_at": "2026-04-30T12:34:56Z",
    "result_count": 8,
    "results": [
      {
        "id": "chunk-x",
        "score": 0.91,
        "text": "",
        "metadata": { "rank": 1 }
      }
    ]
  },
  "rerun": {
    "search_id": "search_def456",
    "results": [
      {
        "id": "chunk-x",
        "score": 0.89,
        "text": "A player is in an offside position if...",
        "metadata": {}
      }
    ],
    "diff": {
      "added": ["chunk-z"],
      "removed": ["chunk-y"],
      "shared": 5,
      "rank_correlation": 0.83
    }
  }
}

Note: When include_original is true, the original result items contain id, score, and rank metadata only. The original chunk text is not stored in the search event ledger, so the text field is empty.

Response fields

Field	Type	Description
`original`	object	Summary of the captured first run.
`original.search_id`	string	Original `search_id`.
`original.query`	string	Query text from the original run.
`original.bucket_id`	string	Bucket searched in the original run.
`original.created_at`	string \| null	ISO 8601 timestamp of the original session.
`original.result_count`	integer	Number of results captured in the original run.
`original.results`	array \| null	Original result items when `include_original` is `true`.
`rerun`	object	Summary of the new run.
`rerun.search_id`	string	New `search_id` for the rerun.
`rerun.results`	array	Result items from the rerun.
`rerun.diff`	object	Diff metrics comparing the two result sets.

Diff metrics

Field	Type	Description
`added`	array of strings	IDs present in the rerun but not in the original.
`removed`	array of strings	IDs present in the original but not in the rerun.
`shared`	integer	Number of IDs present in both result sets.
`rank_correlation`	number \| null	Spearman rank correlation over shared IDs. `1.0` means identical order; `-1.0` means reversed. `null` when fewer than 2 shared IDs.

Error examples

404 Not Found — the search_id does not exist for the organization.

{
  "detail": "search_id not found for this org"
}

422 Unprocessable Entity — the captured session is missing required query or bucket information.

{
  "detail": "Original search lacks query/bucket — replay not possible"
}

API Versions

Only v1 is available for Search Replay. There is no deprecated version.

Limitations

The original full request payload — including filter, top_k, and other parameters — is not yet persisted. An unmodified replay therefore runs with default search parameters, not bit-for-bit identical settings.
Future releases will persist the full BucketSearchRequest at session creation so unmodified replays are reproducible.