> ## Documentation Index
> Fetch the complete documentation index at: https://runinfra.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Rerank

> POST /v1/rerank, relevance scoring that reorders candidate documents against a query, for a model deployed in your workspace.

```http theme={"dark"}
POST https://api.runinfra.ai/v1/rerank
```

This operation answers for a rerank model you have deployed in your workspace. Send a query and the candidate documents, and the response scores every candidate against that query and returns them in ranked order. It is the second stage of a retrieval pipeline: a fast first-stage search proposes candidates, this call decides which of them actually answer the query.

<RequestExample>
  ```python Python theme={"dark"}
  import os
  import requests

  response = requests.post(
      "https://api.runinfra.ai/v1/rerank",
      headers={"Authorization": f"Bearer {os.environ['RUNINFRA_GATEWAY_KEY']}"},
      json={
          "model": os.environ["MODEL_ID"],
          "query": "How do I rotate an API key?",
          "texts": [
              "Invoices are issued at the end of each month.",
              "Rotate a key from the workspace settings page.",
              "Deleting a key revokes it immediately.",
          ],
          "top_n": 2,
      },
      timeout=60,
  )
  for row in response.json()["results"]:
      print(row["index"], row["score"])
  ```

  ```typescript TypeScript theme={"dark"}
  const response = await fetch("https://api.runinfra.ai/v1/rerank", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.RUNINFRA_GATEWAY_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      model: process.env.MODEL_ID,
      query: "How do I rotate an API key?",
      texts: [
        "Invoices are issued at the end of each month.",
        "Rotate a key from the workspace settings page.",
        "Deleting a key revokes it immediately.",
      ],
      top_n: 2,
    }),
  });
  const { results } = await response.json();
  ```

  ```bash cURL theme={"dark"}
  curl https://api.runinfra.ai/v1/rerank \
    -H "Authorization: Bearer $RUNINFRA_GATEWAY_KEY" \
    -H "Content-Type: application/json" \
    -d "{
          \"model\": \"$MODEL_ID\",
          \"query\": \"How do I rotate an API key?\",
          \"texts\": [
            \"Invoices are issued at the end of each month.\",
            \"Rotate a key from the workspace settings page.\",
            \"Deleting a key revokes it immediately.\"
          ],
          \"top_n\": 2
        }"
  ```
</RequestExample>

## Request fields

| Field       | Meaning                                                                                                                                           |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`     | Required. The id of a rerank model deployed in your workspace. `GET /v1/models` lists the ids your key can reach.                                 |
| `query`     | Required. The text every candidate is scored against.                                                                                             |
| `texts`     | The candidates as an array of strings. Send this or `documents`.                                                                                  |
| `documents` | The candidates as an array of objects, each with a `text` and an optional `id` that is carried back on the matching result. Send this or `texts`. |
| `top_n`     | Optional. Return only the first `n` results of the ranked list instead of all of them.                                                            |

Candidates keep the order you sent them in. Every result names its candidate by `index`, the position in the array you supplied, so you can join the scores back onto your own records without matching on text.

## Response

| Field            | Meaning                                                                                                 |
| ---------------- | ------------------------------------------------------------------------------------------------------- |
| `object`         | `runinfra.rerank`.                                                                                      |
| `model`          | The deployed model id that served the request.                                                          |
| `upstream_model` | The model that produced the scores.                                                                     |
| `scores`         | One `{ index, score }` entry per ranked candidate, in ranked order.                                     |
| `rankings`       | The same ranked order, each entry also carrying the candidate's `text`, and its `id` when you sent one. |
| `results`        | Identical to `rankings`, under the name most retrieval clients expect.                                  |
| `document_count` | How many candidates were scored.                                                                        |
| `usage`          | `prompt_tokens` and `total_tokens` for the call. Reranking produces no output tokens.                   |

The values below are an example, not a measurement.

```json theme={"dark"}
{
  "object": "runinfra.rerank",
  "model": "your-deployed-rerank-model",
  "upstream_model": "your-deployed-rerank-model",
  "scores": [
    { "index": 1, "score": 0.93 },
    { "index": 2, "score": 0.48 }
  ],
  "rankings": [
    { "index": 1, "score": 0.93, "text": "Rotate a key from the workspace settings page." },
    { "index": 2, "score": 0.48, "text": "Deleting a key revokes it immediately." }
  ],
  "results": [
    { "index": 1, "score": 0.93, "text": "Rotate a key from the workspace settings page." },
    { "index": 2, "score": 0.48, "text": "Deleting a key revokes it immediately." }
  ],
  "document_count": 3,
  "usage": { "prompt_tokens": 41, "total_tokens": 41 }
}
```

Scores are comparable within one response, because every candidate was judged against the same query. They are not a probability and they do not carry meaning across two different queries, so pick a cutoff by ranking position or by a threshold you tuned on your own data, never by assuming a fixed scale.

## Candidate limits

A single call scores at most 100 candidates. The deployment serving the request also carries its own verified batch limit, and the lower of the two applies. Over either limit the call fails with `rerank_document_limit_exceeded`, and the message names the limit that was hit. Split a larger candidate set across calls and merge the ranked lists yourself.

## Retries

Send an `Idempotency-Key` and a retried call replays the stored result instead of scoring again, so a lost response never costs a second run. See [Idempotent retries](/docs/api-reference/idempotent-retries) for the header rules and the replay headers.

## Billing

Reranking bills on the terms of the deployment serving it.

## Errors

Failures use the same [OpenAI-style error envelope](/docs/api-reference/errors) as every other `/v1` operation. These codes are specific to this endpoint.

| `error.code`                     | Meaning                                                                                                    |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `invalid_rerank_request`         | The request has no `query`, or no usable entry in `texts` or `documents`.                                  |
| `rerank_document_limit_exceeded` | More candidates than the request limit or the deployment's batch limit allows.                             |
| `unsupported_rerank_backend`     | The id in `model` resolves to a deployment this route cannot serve.                                        |
| `rerank_response_too_large`      | The ranked response is too large to retain for idempotent replay. Send `top_n`, or shorter candidate text. |

A `404` `model_not_found` means the id in `model` is not a model this key can reach. Deploy the model in your workspace, then call `GET /v1/models` to confirm the id before retrying.

## Related

<Columns cols={3}>
  <Card title="Embeddings" icon="database" href="/docs/api-reference/embeddings">
    Produce the vectors your first-stage search retrieves before this call reorders them.
  </Card>

  <Card title="Models" icon="list" href="/docs/api-reference/models">
    Discover the model ids your key can reach.
  </Card>

  <Card title="Errors" icon="circle-alert" href="/docs/api-reference/errors">
    Handle validation, availability, and rate-limit failures.
  </Card>
</Columns>