Reranking

POST /v1/rerank orders a list of documents by how well each answers a query. It is a drop-in replacement for Cohere Rerank, and it is the same reranker Hindsight uses for recall, tuned for agent memory: short factual snippets and questions about who did what, when.

Use it as the second stage of a search pipeline. Retrieve a generous candidate set with keyword or vector search, then rerank it and keep the top few.

Model: hindsight-rerank-1

Quick Start

curl

curl https://inference.hindsight.vectorize.io/v1/rerank \
  -H "Authorization: Bearer $HINDSIGHT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "hindsight-rerank-1",
    "query": "When did Caroline go to the support group?",
    "documents": [
      "Caroline is planning a camping trip next month.",
      "Caroline went to a support group on 7 May.",
      "Melanie painted a sunrise last year."
    ],
    "top_n": 1
  }'

Python (Cohere SDK)

import cohere

# The Cohere SDK appends /v1/rerank itself, so pass the host only.
co = cohere.ClientV2(
    api_key="<your Hindsight API key>",
    base_url="https://inference.hindsight.vectorize.io",
)

response = co.rerank(
    model="hindsight-rerank-1",
    query="When did Caroline go to the support group?",
    documents=[
        "Caroline is planning a camping trip next month.",
        "Caroline went to a support group on 7 May.",
        "Melanie painted a sunrise last year.",
    ],
)
for r in response.results:
    print(r.index, r.relevance_score)

Self-hosted Hindsight

Self-hosted Hindsight can rerank recall results with this API through its Cohere provider. Set:

HINDSIGHT_API_RERANKER_PROVIDER=cohere
HINDSIGHT_API_RERANKER_COHERE_BASE_URL=https://inference.hindsight.vectorize.io/v1/rerank
HINDSIGHT_API_RERANKER_COHERE_MODEL=hindsight-rerank-1
HINDSIGHT_API_RERANKER_COHERE_API_KEY=<your Hindsight API key>

Unlike the SDK, Hindsight's provider uses the base URL verbatim, so include /v1/rerank.

Request

Field	Type	Required	Description
query	string	Yes	The question or search text
documents	array	Yes	Up to 1,000 documents, each a string or an object with a text field
model	string	No	hindsight-rerank-1 (the default)
top_n	integer	No	Return only the best n results. Omit it to get a score for every document
return_documents	boolean	No	Include each document's text in the results
prune	boolean	No	Drop documents the model judges irrelevant. See Pruning

Documents longer than 4,096 tokens are truncated, not rejected. Sending more than 1,000 documents returns 400.

Response

{
  "id": "5b0c6a0e-…",
  "results": [
    { "index": 1, "relevance_score": 1.0 },
    { "index": 0, "relevance_score": 0.667 },
    { "index": 2, "relevance_score": 0.333 }
  ],
  "meta": {
    "api_version": { "version": "2" },
    "billed_units": { "search_units": 1, "input_tokens": 64 }
  }
}

results is sorted best first. index points back into the documents you sent. With return_documents: true, each result also has "document": {"text": "…"}.

Understanding Scores

Scores are rank positions, not probabilities

relevance_score reflects a document's position in the ranking. The best document scores 1.0, and scores step down evenly from there. A score of 0.5 means "ranked halfway down this list", not "50% relevant".

So a fixed threshold such as relevance_score > 0.7 keeps a fixed fraction of whatever you sent, relevant or not. To drop irrelevant documents, use prune or top_n instead.

Pruning

With "prune": true, the model also decides where the relevant documents end. Documents below that cut get a score of 0.0 and are removed from results. The response can therefore hold fewer results than you sent, or none at all if nothing is relevant.

Use pruning when you would otherwise pass every reranked document on, for example into an LLM prompt, and want to keep only the ones that matter.

Billing

Reranking costs $0.05 per 1M input tokens, counting the query and the documents as sent to the model. For large candidate sets the reranker compares documents in rounds, and some documents are sent more than once. meta.billed_units.input_tokens reports exactly what was billed.

search_units is reported for Cohere compatibility only. Billing uses input tokens.