How to beginner · 3 min read

How to use Cohere reranker

Q: How to use Cohere reranker

Use the cohere Python SDK to call the rerank endpoint by providing a query and a list of candidate texts. The API returns a relevance score for each candidate, allowing you to reorder them by relevance efficiently.

Quick answer

Use the cohere Python SDK to call the rerank endpoint by providing a query and a list of candidate texts. The API returns a relevance score for each candidate, allowing you to reorder them by relevance efficiently.

PREREQUISITES

Python 3.8+
Cohere API key (free tier available)
pip install cohere

Setup

Install the official cohere Python package and set your API key as an environment variable.

bash

pip install cohere

Step by step

This example shows how to use the Cohere reranker to score and reorder candidate texts based on a query.

python

import os
import cohere

# Initialize the Cohere client with your API key
client = cohere.Client(api_key=os.environ["COHERE_API_KEY"])

# Define the query and candidate texts
query = "Best programming languages for AI development"
candidates = [
    "Python is widely used for AI and machine learning.",
    "JavaScript is popular for web development.",
    "C++ is used for system programming and games.",
    "Java is common in enterprise applications."
]

# Call the rerank endpoint
response = client.rerank(
    query=query,
    documents=candidates
)

# Extract and print reranked results
reranked = sorted(
    zip(candidates, response.ranks),
    key=lambda x: x[1]
)

print("Reranked candidates by relevance:")
for doc, rank in reranked:
    print(f"Rank {rank}: {doc}")

output

Reranked candidates by relevance:
Rank 0: Python is widely used for AI and machine learning.
Rank 1: Java is common in enterprise applications.
Rank 2: C++ is used for system programming and games.
Rank 3: JavaScript is popular for web development.

Common variations

You can rerank with multiple queries or use the top_n parameter to limit results. The cohere SDK supports async usage with asyncio. You can also specify different reranker models if available.

python

import asyncio
import os
import cohere

async def async_rerank():
    client = cohere.Client(api_key=os.environ["COHERE_API_KEY"])
    query = "Top AI frameworks"
    candidates = [
        "TensorFlow is a popular AI framework.",
        "React is a JavaScript library for UI.",
        "PyTorch is widely used for deep learning."
    ]
    response = await client.rerank(
        query=query,
        documents=candidates,
        top_n=2
    )
    reranked = sorted(zip(candidates, response.ranks), key=lambda x: x[1])
    for doc, rank in reranked:
        print(f"Rank {rank}: {doc}")

asyncio.run(async_rerank())

output

Rank 0: PyTorch is widely used for deep learning.
Rank 1: TensorFlow is a popular AI framework.
Rank 2: React is a JavaScript library for UI.

Troubleshooting

If you get an authentication error, verify your COHERE_API_KEY environment variable is set correctly.
If reranking results seem off, ensure your query and candidates are relevant and well-formed.
Check your network connection if requests time out.

✅

Key Takeaways

Use the cohere.Client and its rerank method to reorder candidates by relevance.
Pass a single query string and a list of candidate texts to get ranked results.
You can use async calls and limit results with top_n for efficiency.
Always set your COHERE_API_KEY in environment variables for authentication.
Validate input quality to improve reranking accuracy.

Verified 2026-04 · cohere reranker

Verify ↗