Request
Response
Parameters
string
required
The name of the model to use for reranking. Supported model:
cohere-rerank-v4.0-fast.string
required
The search query used to rank the documents.
array
required
The list of documents to be reranked. Supports both simple string arrays and structured object arrays.
integer
The number of most relevant documents to return.
array of strings
Determines which fields in a structured object document are used for ranking. If omitted, the API automatically determines how to rank structured documents.
boolean
default:"true"
If set to
true, the ranked documents will be included in the response.integer
Request priority (from 0 to 999). A lower value indicates a higher priority.
integer
The maximum number of tokens processed per document before truncation.
Returns
The response contains a unique ID, ranked results, and API usage metadata.string
A unique identifier for the rerank request.
array
The ordered list of ranked documents, sorted by relevance score descending.
object
Metadata containing the API version and billed units.
Behavior & Validation Notes
1. rank_fields is Optional
The request succeeds even when rank_fields is omitted. The API automatically determines how to rank structured documents.
2. rank_fields Controls Ranking
Providing specific fields in rank_fields (e.g., ["title"]) restricts the model to only use those fields for calculation, overriding other fields (such as text).
3. Document Normalization in Response
Whenreturn_documents is enabled, the API returns a normalized document containing only the text field. Original metadata fields (such as title, author, year, etc.) are stripped out of the response.
4. Independence of rank_fields and Response Inclusion
Even if ranking is performed on fields like title, the returned document in results.document will still be normalized to the text field.
5. Billing based on Search Units
Billing is calculated solely on search units (e.g.,billed_units.search_units). There is no output token cost or separate pricing for input tokens.