---
title: "Rerank"
method: POST
path: "/v1/rerank"
tags: ["Search Foundation Models"]
---

# Rerank

`POST /v1/rerank`

Rerank documents by relevance to a query.

World-class reranker for maximizing search relevancy and RAG accuracy.

## Request body

- union
  - TextRerankerRequest — Text reranking request for v1/v2 models.
    - `query` string, required — The search query to rank documents against.
    - `top_n` integer, nullable — Number of top results to return. If not set, returns all documents.
    - `return_documents` boolean, nullable — If true (default), includes document content in each result.
    - `model` 'jina-reranker-v2-base-multilingual' | 'jina-reranker-v1-tiny-en' | 'jina-reranker-v1-turbo-en' | 'jina-reranker-v1-base-en' | 'jina-colbert-v1-en' | 'jina-colbert-v2', required — The reranking model to use.
    - `documents` union[], required — Documents to rank: strings or `TextDoc` objects.
      - union
        - string
        - TextDoc
          - `text` string, required — Text content to process.
  - RerankerM0Request — Multimodal reranking for text and images.
    - `query` union, required — The query to rank documents against: a text string, or an image object (`{"image": <url|base64>}`) for a visual query.
      - string
      - ImageDoc
        - `image` string, required — Image as a URL or base64-encoded string.
    - `top_n` integer, nullable — Number of top results to return. If not set, returns all documents.
    - `return_documents` boolean, nullable — If true (default), includes document content in each result.
    - `model` 'jina-reranker-m0', required — The multimodal reranking model to use.
    - `documents` union[], required — Documents to rank: strings, `TextDoc`, or `ImageDoc` objects.
      - union
        - string
        - TextDoc
          - `text` string, required — Text content to process.
        - ImageDoc
          - `image` string, required — Image as a URL or base64-encoded string.
  - RerankerV3Request — Listwise reranker for high-quality multilingual retrieval. `max_doc_length` is an optional override; when omitted it stays `None` and the serving executor applies its configured per-model default, keeping that default in one place.
    - `query` string, required — The search query to rank documents against.
    - `top_n` integer, nullable — Number of top results to return. If not set, returns all documents.
    - `return_documents` boolean, nullable — If true (default), includes document content in each result.
    - `model` 'jina-reranker-v3' | 'jina-reranker-v3.5', required — The reranking model to use.
    - `documents` union[], required — Documents to rank: strings or `TextDoc` objects.
      - union
        - string
        - TextDoc
          - `text` string, required — Text content to process.
    - `max_doc_length` integer, nullable — Maximum tokens per document (1-8192). Omit to use the model's default (2048 for jina-reranker-v3, 8192 for jina-reranker-v3.5).
    - `return_embeddings` boolean, nullable — If true, returns the document embedding alongside the relevance score.

## Response `200`

Successful Response

- RerankingResponse — Response containing ranked documents.
  - `model` string, required — The model used for reranking.
  - `object` string — Object type, always `list`.
  - `usage` BaseUsage, required
    - `total_tokens` integer, required — Total number of tokens processed.
  - `results` RerankingResult[], required — Ranked documents, sorted by relevance score descending.
    - `index` integer, required — Position of this document in the original input list.
    - `relevance_score` number, required — Relevance score. Higher is more relevant.
    - `document` union — Document content, if `return_documents=true`.
      - string
      - TextDoc
        - `text` string, required — Text content to process.
      - ImageDoc
        - `image` string, required — Image as a URL or base64-encoded string.
    - `embedding` number[], nullable — Document embedding, if `return_embeddings=true`.

## Other responses

- `400` — - **INPUT_MODEL_NOT_FOUND**: Model 'model_name' not found. Available models: .... - **INPUT_INVALID_LABELS**: Invalid training labels. At least {min_labels} unique labels are required for training. - **INPUT_LABEL_LIMIT_EXCEEDED**: Label limit exceeded: {current} labels provided, maximum N allowed for your plan. Reduce the number of labels or upgrade your plan at https://jina.ai/api-dashboard/key-manager. - **INPUT_TOKEN_LIMIT_EXCEEDED**: Input text exceeds the model's maximum of {max_tokens} tokens. Use 'truncate: true' to automatically truncate, or split into smaller chunks.
- `401` — - **AUTH_MISSING_API_KEY**: Authentication required. Provide your API key via the Authorization header: 'Authorization: Bearer <api-key>'. Get your API key at https://jina.ai/api-dashboard/key-manager. - **AUTH_INVALID_API_KEY**: Invalid API key. Verify your API key at https://jina.ai/api-dashboard/key-manager or generate a new one. - **AUTH_INVALID_FORMAT**: Invalid authorization format. Use 'Authorization: Bearer <api-key>' with a valid Jina API key (65 characters, starts with 'jina_').
- `403` — - **AUTHZ_INSUFFICIENT_BALANCE**: Insufficient account balance. Top up your account at https://jina.ai/api-dashboard/key-manager. - **AUTHZ_RESOURCE_LIMIT_EXCEEDED**: Resource limit exceeded for your plan. Current: {current}, limit: N. Delete existing resources or upgrade your plan at https://jina.ai/api-dashboard/key-manager.
- `404` — - **RESOURCE_NOT_FOUND**: {resource_type} '{resource_id}' not found or access denied. Verify the ID and your permissions.
- `409` — - **CONFLICT_RESOURCE_BUSY**: {resource_type} '{resource_id}' is currently being modified. Please retry after a few moments.
- `422` — Validation Error
- `429` — - **RATE_REQUEST_LIMIT_EXCEEDED**: Request rate limit exceeded: {current}/N requests per minute. Reduce request frequency or upgrade your plan at https://jina.ai/api-dashboard/key-manager. - **RATE_TOKEN_LIMIT_EXCEEDED**: Token rate limit exceeded: {current:,}/{limit:,} tokens per minute. Reduce batch sizes or upgrade your plan at https://jina.ai/api-dashboard/key-manager. - **RATE_CONCURRENCY_LIMIT_EXCEEDED**: Concurrency limit exceeded: {current}/N concurrent requests. Wait for pending requests to complete before sending new ones. - **RATE_IP_LIMIT_EXCEEDED**: IP rate limit exceeded. Too many requests from this IP address. Reduce request frequency.
- `500` — - **INTERNAL_ERROR**: An unexpected error occurred. If this persists, contact support with the request_id from this response.
- `503` — - **SERVICE_UNAVAILABLE**: Service temporarily unavailable. Please retry with exponential backoff.
- `504` — - **SERVICE_TIMEOUT**: Service request timed out. Try with smaller inputs or retry later.

---

[API](https://skmtc.net/jina/apis/jina-search-foundation-api.md) · [All operations](https://skmtc.net/jina/apis/jina-search-foundation-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/jina/jina-search-foundation-api/versions/0ae64d1cd6e1/schema)