Voyage rerank-3 is a text reranker designed to improve the quality of retrieved evidence. Given a query and a list of candidate documents, it jointly examines each pair and returns the candidates ordered by relevance. Embeddings and keyword search can first narrow a large collection to a manageable shortlist; rerank-3 then applies more detailed relevance assessment to that shortlist. Its output is scored search evidence for an application to display or pass into a separate answer-generation step.
Quality-focused Rerank 3 The maker positions rerank-3 as the accuracy-focused edition and rerank-3-lite as the edition for latency-sensitive search. The third generation updates the backbone and training mixture, with particular improvements on long-document and source-code retrieval compared with the corresponding 2.5 predecessors. The producer evaluates it across technical documentation, code, multilingual material and other document domains. Those results support its retrieval role; select the edition using the questions and candidate documents that matter to your own collection.
Long documents with enough context A long candidate can contain useful context well beyond its opening paragraph. Supply a coherent section or document with its title and relevant surrounding material, so the model can assess how the actual question relates to the content. For a product-policy search, preserve headings and exceptions around the passage of interest. If several retrieved sections come from the same source, retain their document and section identifiers; the application can then show where the selected evidence originated.
The context window is shared by the query and each candidate. The current maker guide specifies 32,000 tokens for that pair, including a query of at most 8,000 tokens. A 3,000-token query therefore leaves at most 29,000 tokens for each document. Prepare the input so its essential content fits, particularly when a long preamble or repeated boilerplate would otherwise consume the window. The documented truncation option defaults to enabled and can shorten oversized query or document text before scoring. Inspect what is retained when passage placement matters.
Code and technical retrieval For a coding assistant’s retrieval stage, candidates can contain function implementations, API documentation or technical explanations as text. Include the symbols, signatures and context needed to distinguish similar candidates. A query such as “Find the function that normalizes paths while preserving a trailing separator” gives a concrete behaviour to match. Attach any relevant language, platform or version constraints. After ranking, examine the selected code and its dependencies before using it as context; a relevance score does not prove that an implementation satisfies every stated requirement.
Instructions define relevance The model retains the instruction-following reranking capability introduced in Rerank 2.5. Prepend or append a concise instruction to the query when the user’s intent needs clarification. For research-document search, explain whether the focus is the title, a particular method or an application domain. For an internal catalogue, specify whether the request concerns installation, troubleshooting or compatibility. Keep that instruction aligned with the question; extra preferences that conflict with the main request can change what the ranking is trying to optimize.
Prepare candidate documents and budgets The input is a list of text strings. Extract usable text from source documents, preserve meaningful section boundaries and keep an ordered record map alongside the list. The maker allows up to 1,000 documents in one request. It also specifies an aggregate input ceiling of 600,000 tokens: query tokens multiplied by the number of documents, plus the sum of all document tokens. This differs from the per-pair context limit. Reducing redundant query text can preserve both pair capacity and the overall request budget.
Count tokens for the relevant model, rather than assuming that a word or character count is a token count. For large candidates, select coherent passages or divide the material by useful headings while retaining parent-source information. Reranking is most useful after the first search has already surfaced plausible candidates: it cannot rank a missing source that never entered the list.
Ranked results and downstream use The result contains relevance scores and indices referring to the original input documents, sorted in descending relevance order. The top_k option limits the number of ranked results returned; otherwise all input candidates are returned. The maker’s REST interface also allows the document text to be included. Use each original index to recover the title, source identifier and any metadata your application needs, then present the selected items or pack the relevant text into an answer’s evidence context.
Inspect the top results against the question and keep source identity visible. A high relative rank does not verify a document’s factual accuracy, and a shortlist containing only poor candidates will still have a first item. Separate relevance selection from deciding whether the selected evidence is sufficient to answer the user.
Edition migration The maker describes rerank-3 as a drop-in successor to rerank-2.5, with the same API semantics and scores calibrated to its corresponding predecessor’s distribution. That compatibility supports retaining an existing retrieval stage and record mapping. Compare meaningful result orderings and any score cutoff on the current corpus before relying on the migration. Keep rerank-3 and rerank-3-lite as distinct choices: shared limits and instruction following do not make their quality and latency priorities identical.
", "aboutText": "Voyage rerank-3 is a text reranker designed to improve the quality of retrieved evidence. Given a query and a list of candidate documents, it jointly examines each pair and returns the candidates ordered by relevance. Embeddings and keyword search can first narrow a large collection to a manageable shortlist; rerank-3 then applies more detailed relevance assessment to that shortlist. Its output is scored search evidence for an application to display or pass into a separate answer-generation step.\n\nQuality-focused Rerank 3\nThe maker positions rerank-3 as the accuracy-focused edition and rerank-3-lite as the edition for latency-sensitive search. The third generation updates the backbone and training mixture, with particular improvements on long-document and source-code retrieval compared with the corresponding 2.5 predecessors. The producer evaluates it across technical documentation, code, multilingual material and other document domains. Those results support its retrieval role; select the edition using the questions and candidate documents that matter to your own collection.\n\nLong documents with enough context\nA long candidate can contain useful context well beyond its opening paragraph. Supply a coherent section or document with its title and relevant surrounding material, so the model can assess how the actual question relates to the content. For a product-policy search, preserve headings and exceptions around the passage of interest. If several retrieved sections come from the same source, retain their document and section identifiers; the application can then show where the selected evidence originated.\n\nThe context window is shared by the query and each candidate. The current maker guide specifies 32,000 tokens for that pair, including a query of at most 8,000 tokens. A 3,000-token query therefore leaves at most 29,000 tokens for each document. Prepare the input so its essential content fits, particularly when a long preamble or repeated boilerplate would otherwise consume the window. The documented truncation option defaults to enabled and can shorten oversized query or document text before scoring. Inspect what is retained when passage placement matters.\n\nCode and technical retrieval\nFor a coding assistant’s retrieval stage, candidates can contain function implementations, API documentation or technical explanations as text. Include the symbols, signatures and context needed to distinguish similar candidates. A query such as “Find the function that normalizes paths while preserving a trailing separator” gives a concrete behaviour to match. Attach any relevant language, platform or version constraints. After ranking, examine the selected code and its dependencies before using it as context; a relevance score does not prove that an implementation satisfies every stated requirement.\n\nInstructions define relevance\nThe model retains the instruction-following reranking capability introduced in Rerank 2.5. Prepend or append a concise instruction to the query when the user’s intent needs clarification. For research-document search, explain whether the focus is the title, a particular method or an application domain. For an internal catalogue, specify whether the request concerns installation, troubleshooting or compatibility. Keep that instruction aligned with the question; extra preferences that conflict with the main request can change what the ranking is trying to optimize.\n\nPrepare candidate documents and budgets\nThe input is a list of text strings. Extract usable text from source documents, preserve meaningful section boundaries and keep an ordered record map alongside the list. The maker allows up to 1,000 documents in one request. It also specifies an aggregate input ceiling of 600,000 tokens: query tokens multiplied by the number of documents, plus the sum of all document tokens. This differs from the per-pair context limit. Reducing redundant query text can preserve both pair capacity and the overall request budget.\n\nCount tokens for the relevant model, rather than assuming that a word or character count is a token count. For large candidates, select coherent passages or divide the material by useful headings while retaining parent-source information. Reranking is most useful after the first search has already surfaced plausible candidates: it cannot rank a missing source that never entered the list.\n\nRanked results and downstream use\nThe result contains relevance scores and indices referring to the original input documents, sorted in descending relevance order. The top_k option limits the number of ranked results returned; otherwise all input candidates are returned. The maker’s REST interface also allows the document text to be included. Use each original index to recover the title, source identifier and any metadata your application needs, then present the selected items or pack the relevant text into an answer’s evidence context.\n\nInspect the top results against the question and keep source identity visible. A high relative rank does not verify a document’s factual accuracy, and a shortlist containing only poor candidates will still have a first item. Separate relevance selection from deciding whether the selected evidence is sufficient to answer the user.\n\nEdition migration\nThe maker describes rerank-3 as a drop-in successor to rerank-2.5, with the same API semantics and scores calibrated to its corresponding predecessor’s distribution. That compatibility supports retaining an existing retrieval stage and record mapping. Compare meaningful result orderings and any score cutoff on the current corpus before relying on the migration. Keep rerank-3 and rerank-3-lite as distinct choices: shared limits and instruction following do not make their quality and latency priorities identical.", "editorialOverlay": { "copy_fields": null, "copy_sha256": null, "copy_source": null, "html_sha256": "e41779a5573c40b9d0184a1917bd969156585929467cfcec95f9e215165b18b9", "module_sha256": "ee9dc1c50b1e6a8fb7fa062030fcb4646b9aaaeb08be513b723a5a92a7290f06", "raw_model_unchanged": true, "schema": "ailoot-native-model-editorial-v1" }, "locale": "en", "methods": [ { "html": "voyageai/rerank-3Voyage rerank-3 is the quality-focused Rerank 3 edition for scoring query-document relevance. It reorders retrieved text candidates, supports natural-language relevance instructions and handles 32,000-token pairs for long-document, code and knowledge-base search.
This description covers the model’s capabilities. Available in Ailoot inputs, outputs and options are listed for the selected method below.
Voyage rerank-3 is a text reranker designed to improve the quality of retrieved evidence. Given a query and a list of candidate documents, it jointly examines each pair and returns the candidates ordered by relevance. Embeddings and keyword search can first narrow a large collection to a manageable shortlist; rerank-3 then applies more detailed relevance assessment to that shortlist. Its output is scored search evidence for an application to display or pass into a separate answer-generation step.
Quality-focused Rerank 3 The maker positions rerank-3 as the accuracy-focused edition and rerank-3-lite as the edition for latency-sensitive search. The third generation updates the backbone and training mixture, with particular improvements on long-document and source-code retrieval compared with the corresponding 2.5 predecessors. The producer evaluates it across technical documentation, code, multilingual material and other document domains. Those results support its retrieval role; select the edition using the questions and candidate documents that matter to your own collection.
Long documents with enough context A long candidate can contain useful context well beyond its opening paragraph. Supply a coherent section or document with its title and relevant surrounding material, so the model can assess how the actual question relates to the content. For a product-policy search, preserve headings and exceptions around the passage of interest. If several retrieved sections come from the same source, retain their document and section identifiers; the application can then show where the selected evidence originated.
The context window is shared by the query and each candidate. The current maker guide specifies 32,000 tokens for that pair, including a query of at most 8,000 tokens. A 3,000-token query therefore leaves at most 29,000 tokens for each document. Prepare the input so its essential content fits, particularly when a long preamble or repeated boilerplate would otherwise consume the window. The documented truncation option defaults to enabled and can shorten oversized query or document text before scoring. Inspect what is retained when passage placement matters.
Code and technical retrieval For a coding assistant’s retrieval stage, candidates can contain function implementations, API documentation or technical explanations as text. Include the symbols, signatures and context needed to distinguish similar candidates. A query such as “Find the function that normalizes paths while preserving a trailing separator” gives a concrete behaviour to match. Attach any relevant language, platform or version constraints. After ranking, examine the selected code and its dependencies before using it as context; a relevance score does not prove that an implementation satisfies every stated requirement.
Instructions define relevance The model retains the instruction-following reranking capability introduced in Rerank 2.5. Prepend or append a concise instruction to the query when the user’s intent needs clarification. For research-document search, explain whether the focus is the title, a particular method or an application domain. For an internal catalogue, specify whether the request concerns installation, troubleshooting or compatibility. Keep that instruction aligned with the question; extra preferences that conflict with the main request can change what the ranking is trying to optimize.
Prepare candidate documents and budgets The input is a list of text strings. Extract usable text from source documents, preserve meaningful section boundaries and keep an ordered record map alongside the list. The maker allows up to 1,000 documents in one request. It also specifies an aggregate input ceiling of 600,000 tokens: query tokens multiplied by the number of documents, plus the sum of all document tokens. This differs from the per-pair context limit. Reducing redundant query text can preserve both pair capacity and the overall request budget.
Count tokens for the relevant model, rather than assuming that a word or character count is a token count. For large candidates, select coherent passages or divide the material by useful headings while retaining parent-source information. Reranking is most useful after the first search has already surfaced plausible candidates: it cannot rank a missing source that never entered the list.
Ranked results and downstream use The result contains relevance scores and indices referring to the original input documents, sorted in descending relevance order. The top_k option limits the number of ranked results returned; otherwise all input candidates are returned. The maker’s REST interface also allows the document text to be included. Use each original index to recover the title, source identifier and any metadata your application needs, then present the selected items or pack the relevant text into an answer’s evidence context.
Inspect the top results against the question and keep source identity visible. A high relative rank does not verify a document’s factual accuracy, and a shortlist containing only poor candidates will still have a first item. Separate relevance selection from deciding whether the selected evidence is sufficient to answer the user.
Edition migration The maker describes rerank-3 as a drop-in successor to rerank-2.5, with the same API semantics and scores calibrated to its corresponding predecessor’s distribution. That compatibility supports retaining an existing retrieval stage and record mapping. Compare meaningful result orderings and any score cutoff on the current corpus before relying on the migration. Keep rerank-3 and rerank-3-lite as distinct choices: shared limits and instruction following do not make their quality and latency priorities identical.
POST /v1/reranktextrerank| Field | Type | Requirement | Values & limits | Default |
|---|---|---|---|---|
Fielddocuments | Typearray | RequirementRequired | Values & limits | Default— |
Fieldmodel | Typestring | RequirementRequired | Values & limits voyageai/rerank-3 | Default— |
Fieldprovider | Typeschema | RequirementOptional | Values & limits | Default— |
Fieldquery | Typestring | RequirementRequired | Values & limits | Default— |
Fieldsession_id | Typestring | RequirementOptional | Values & limits | Default— |
Fieldtop_n | Typeinteger | RequirementOptional | Values & limits Minimum: 1 | Default— |
Fieldtrace | Typeschema | RequirementOptional | Values & limits | Default— |
Fielduser | Typestring | RequirementOptional | Values & limits | Default— |
Fielddocuments[].text | Typestring | RequirementOptional | Values & limits | Default— |
Fielddocuments[].image | Typestring | RequirementOptional | Values & limits | Default— |
text_rerank · Required: query, documents array with minItems1
| Parameter | Contract |
|---|---|
Parametercontent_type | Contractapplication/json |
Parameterrequired | Contractmodel, query, documents |
Parametermaterial_types | Contracttext |
Parameteroptional_controls | Contractprovider, session_id, top_n, trace, user |
Parametermultimodal_input_binding | Contractnull |
Lifecycle: synchronous
Send the exact model ID and retain the complete native response.
Tariff references do not add request options. Supported parameters are listed for the selected method.
Match each charge to the conditions shown. Use one rate for each set of alternative configurations.
| Configuration | Rate schedule | Billing unit | Charge |
|---|---|---|---|
| ConfigurationBase token rates | Rate scheduleBase rate | Billing unit— | Charge Input · Input tokens — / 1K tokens Output · Output tokens — / 1K tokens Input · Cache read — / 1K tokens Input · Cache write — / 1K tokens Input · Cache write, 1 hour — / 1K tokens |
| ConfigurationUltra | Rate schedule— | Billing unit/ 1K tokens | Charge Input · input token $0.0001 / 1K tokens |
Ailoot reserves an estimated amount before a request. After the result, it settles the final charge from measured usage. Streaming settlement uses the final usage record. How reservation and settlement work →
{\n "documents": [\n "Paris is the capital of France.",\n "Berlin is the capital of Germany."\n ],\n "model": "voyageai/rerank-3",\n "query": "What is the capital of France?",\n "top_n": 3\n}set -eu\n: "${AILOOT_API_KEY:?Set your Ailoot API key}"\n: "${AILOOT_REQUEST_FILE:?Set your actual JSON request file}"\nexport AILOOT_REQUEST_FILE\npython3 - <<'PY_REQUEST'\nimport json,os\nfrom pathlib import Path\np=json.loads(Path(os.environ['AILOOT_REQUEST_FILE']).read_text(encoding='utf-8'))\nif not isinstance(p,dict): raise SystemExit('Request must be a JSON object')\np['model']='voyageai/rerank-3'\nPath('request.json').write_text(json.dumps(p,ensure_ascii=False),encoding='utf-8')\nPY_REQUEST\ncurl --fail-with-body --silent --show-error https://api.ailoot.ai/v1/rerank \\\n -H "Authorization: Bearer $AILOOT_API_KEY" -H 'Content-Type: application/json' \\\n --data-binary @request.json -D response-headers.txt -o result.json\npython3 - <<'PY_RESULT'\nimport json\nfrom pathlib import Path\nprint(json.dumps(json.loads(Path('result.json').read_text()),ensure_ascii=False,indent=2))\nPY_RESULT\njson
Keep every complete returned response, file and content part.
Every actual result index, finite relevance_score and original document object is retained. Indices bind the original document array. Entire original JSON is stored and returned only after settlement.
Preserve original operation and full/partial reply; do not replay POST.
| Field | Type |
|---|---|
Fieldmodel | Typestring |
Fieldid | Typestring |
Fieldprovider | Typestring |
Fieldresults[].index | Typeinteger |
Fieldresults[].relevance_score | Typenumber |
Fieldresults[].document.text | Typestring |
Fieldresults[].document.image | Typestring |
Fieldusage.search_units | Typeinteger |
Fieldusage.total_tokens | Typeinteger |
Fieldusage.cost | Typenumber |
| Response | Condition | Next step |
|---|---|---|
Response400 · invalid_request_error | ConditionInvalid required field, representation or value | Next stepCorrect the indicated request field. |
Ailoot Ultra voyageai/rerank-3
Use the method paths shown above.