Rerank

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.

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"])

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();

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

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.

{
  "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 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 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.

Embeddings

Produce the vectors your first-stage search retrieves before this call reorders them.

Models

Discover the model ids your key can reach.

Errors

Handle validation, availability, and rate-limit failures.

Start here

Guides

API reference

Request fields

Response

Candidate limits

Retries

Billing

Errors

Embeddings

Models

Errors

​Request fields

​Response

​Candidate limits

​Retries

​Billing

​Errors

​Related

Embeddings

Models

Errors

Request fields

Response

Candidate limits

Retries

Billing

Errors

Related