Ladder reads a query and up to 100 candidate documents and scores how well each one answers the query. Run it on the top 20 to 100 results from keyword or vector search: it reads every pair closely, so the right answer moves to the top.
It also answers Cohere and Jina-style requests at /v1/rerank.
Use it
curl https://labs.greatwork.company/v1/run \
-H "Authorization: Bearer $GWL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "ladder-1",
"input": "can I get my money back",
"documents": [
"Our offices are open 9 to 5.",
"Refunds are issued within 30 days of purchase to your original payment method.",
"We ship to 40 countries.",
"To cancel a subscription, open Settings and choose Billing."
],
"return_documents": true
}'const res = await fetch("https://labs.greatwork.company/v1/run", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.GWL_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
"model": "ladder-1",
"input": "can I get my money back",
"documents": [
"Our offices are open 9 to 5.",
"Refunds are issued within 30 days of purchase to your original payment method.",
"We ship to 40 countries.",
"To cancel a subscription, open Settings and choose Billing."
],
"return_documents": true
}),
});
const { output, usage } = await res.json();import os, requests
res = requests.post(
"https://labs.greatwork.company/v1/run",
headers={"Authorization": f"Bearer {os.environ['GWL_API_KEY']}"},
json={
"model": "ladder-1",
"input": "can I get my money back",
"documents": [
"Our offices are open 9 to 5.",
"Refunds are issued within 30 days of purchase to your original payment method.",
"We ship to 40 countries.",
"To cancel a subscription, open Settings and choose Billing."
],
"return_documents": True
},
)
output = res.json()["output"]Set GWL_API_KEY to a key from your dashboard. The bare name ladder works too and follows new versions. Also answers POST /v1/rerank (Cohere and Jina): see compatible endpoints.
Options
input: The query (a string).
| Name | Type | Default | What it does |
|---|---|---|---|
documents required | string[] | 1 to 100 candidate texts. Each is read up to about 1,500 characters. | |
top_n | integer | Return only the best N. | |
return_documents | boolean | false | Include each document's text in the results. |
Output
| Field | Type | Meaning |
|---|---|---|
results | object[] | Best first: index (position in documents), score (0 to 1), and document with return_documents. |
Every response wraps this in {"id", "model", "output", "usage": {"units", "unit", "cost_usd"}, "latency_ms"}.
Examples
FAQ search
{
"model": "ladder-1",
"input": "can I get my money back",
"documents": [
"Our offices are open 9 to 5.",
"Refunds are issued within 30 days of purchase to your original payment method.",
"We ship to 40 countries.",
"To cancel a subscription, open Settings and choose Billing."
],
"return_documents": true
}{
"results": [
{
"index": 1,
"score": 0.2572,
"document": "Refunds are issued within 30 days of purchase to your original payment method."
},
{
"index": 3,
"score": 0.0156,
"document": "To cancel a subscription, open Settings and choose Billing."
},
{
"index": 0,
"score": 0.0022,
"document": "Our offices are open 9 to 5."
},
{
"index": 2,
"score": 0.0022,
"document": "We ship to 40 countries."
}
]
}Captured on our production servers: 202 ms, 4 documents, $0.00004.
Good for
- Improve RAG retrieval
- Reorder site search results
- Pick the best FAQ answer for a question
- Match resumes to a job description
Limits and caveats
- Weaker on long technical, legal, medical and code documents.
- Scores rank documents for one query; don't compare them across queries.
Pricing
$0.01 per 1,000 documents. One unit per document reranked. Failed calls aren't charged, and a call never costs more than its estimate (POST /v1/estimate tells you before you run it).
Built on
Horizon-Labs/multilingual-reranker-small, 141M (mmBERT-small encoder) parameters. License: Apache-2.0. We run it on our servers.