---
title: "Rerank documents"
method: POST
path: "/rerank"
tags: ["Rerank"]
---

# Rerank documents

`POST /rerank`

Text reranking for verified TEI deployments and multimodal document reranking for compatible vLLM vision rerank deployments. Flat workspace requests are replay-safe when an Idempotency-Key is provided; pipeline-scoped rerank helpers are sent once.

## Request body

- union
  - object
    - `model` string, required
    - `query` string, required
    - `texts` string[], required
    - `documents` RerankDocument[]
      - union
        - string
        - object
          - `id` string
          - `text` string, required
        - object — Multimodal document shape for compatible vLLM vision rerank deployments. TEI rerank deployments are text-only.
          - `id` string
          - `content` RerankContentPart[], required
            - union
              - …
    - `top_n` integer — Optional number of ranked results to return.
  - object
    - `model` string, required
    - `query` string, required
    - `texts` string[]
    - `documents` RerankDocument[], required
      - union
        - string
        - object
          - `id` string
          - `text` string, required
        - object — Multimodal document shape for compatible vLLM vision rerank deployments. TEI rerank deployments are text-only.
          - `id` string
          - `content` RerankContentPart[], required
            - union
              - …
    - `top_n` integer — Optional number of ranked results to return.

## Response `200`

Rerank response

- RerankResponse
  - `object` string, required
  - `model` string, required
  - `upstream_model` string
  - `scores` RerankScore[], required
    - `index` integer, required
    - `score` number, required
  - `rankings` RerankResult[], required
    - `index` integer, required
    - `score` number, required
    - `id` string
    - `text` string
    - `content` RerankContentPart[]
      - union
        - object
          - `type` 'text', required
          - `text` string, required
        - object
          - `type` 'image_url', required
          - `image_url` union, required
            - string
            - object
              - …
        - object
          - `type` 'video_url', required
          - `video_url` union, required
            - string
            - object
              - …
  - `results` RerankResult[], required
    - `index` integer, required
    - `score` number, required
    - `id` string
    - `text` string
    - `content` RerankContentPart[]
      - union
        - object
          - `type` 'text', required
          - `text` string, required
        - object
          - `type` 'image_url', required
          - `image_url` union, required
            - string
            - object
              - …
        - object
          - `type` 'video_url', required
          - `video_url` union, required
            - string
            - object
              - …
  - `document_count` integer, required
  - `usage` Usage
    - `cost` number — The calculated cost of this request in US dollars, to eight decimals: the settlement formula over the tokens the provider reported. Present on hosted models; absent on workspace deployments. 0 during a promotional free window and for a response with no billable output. runinfra.cost_microcents is the canonical integer.
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
    - `prompt_tokens_details` object — Present on every hosted model response. cached_tokens is the count of input tokens billed at the cached input rate, the figure the cost was computed with; 0 when nothing was billed as cached, including a response that settled at zero and a model whose cache is shared across tenants. runinfra.cached_input_tokens carries the same number.
      - `cached_tokens` integer
    - `runinfra` RunInfraUsageMetadata
      - `cost_microcents` integer — The calculated cost of this request in microcents (one cent is 1,000,000 microcents), the ledger unit settlement uses; the canonical figure. usage.cost is this value in dollars. The balance is debited in whole cents with sub-cent carry, so a single debit can differ from this by less than a cent.
      - `cached_input_tokens` integer — The count of input tokens billed at the cached input rate on this request, the same number as usage.prompt_tokens_details.cached_tokens. Present on every hosted model response; 0 when nothing was billed as cached.
      - `output_token_accounting` RunInfraOutputTokenAccounting
        - `visible_answer_tokens` 0, required — Final-answer token count classified by the RunInfra proxy for an all-empty generation-limit outcome.
        - `non_answer_completion_tokens` integer, required — Provider-reported completion tokens when the response produced no final answer.
        - `sources` object, required
          - `visible_answer_tokens` 'proxy_classified', required
          - `non_answer_completion_tokens` 'provider_reported', required

## Other responses

- `400` — Malformed request
- `401` — Missing or invalid API key
- `402` — Insufficient credits
- `403` — Key scope mismatch or plan limit exceeded
- `404` — Model or deployment not found
- `409` — Idempotency conflict
- `422` — Request cannot be replayed or processed safely
- `429` — Rate limit exceeded
- `500` — Unexpected gateway error
- `502` — Upstream serving backend transient failure
- `503` — Endpoint stopped, provisioning, or at capacity
- `504` — Gateway timeout

---

[API](https://skmtc.dev/runinfra/apis/runinfra-api.md) · [All operations](https://skmtc.dev/runinfra/apis/runinfra-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runinfra/runinfra-api/revisions/dbd314122f80/schema)