# Ladder (`ladder-1`): Reranking

Put the best search result first. 100+ languages.

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`.

- **Price:** $0.01 per 1,000 documents. One unit per document reranked.
- **Languages:** 100+ languages
- **Input:** The query (a string).
- **Batch:** no, one input per call
- **Status:** live
- **Built on:** [Horizon-Labs/multilingual-reranker-small](https://huggingface.co/Horizon-Labs/multilingual-reranker-small), Apache-2.0, 141M (mmBERT-small encoder)
- **Compatible endpoints:** POST /v1/rerank (Cohere and Jina)

## Request

```bash
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}'
```

## Options

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `input` | string | yes | | The query (a string). |
| `documents` | string[] | yes |  | 1 to 100 candidate texts. Each is read up to about 1,500 characters. |
| `top_n` | integer | no |  | Return only the best N. |
| `return_documents` | boolean | no | `false` | Include each document's text in the results. |

## Output

| Field | Type | Description |
|---|---|---|
| `results` | object[] | Best first: `index` (position in `documents`), `score` (0 to 1), and `document` with `return_documents`. |

The response envelope is always `{"id", "object": "run", "model", "created", "output", "usage": {"units", "unit", "cost_usd", "cost_micros"}, "latency_ms"}`.

## Examples (real outputs from our servers)

### FAQ search

```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
}
```

```json
{
  "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."
    }
  ]
}
```

202 ms, $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.
