> ## Documentation Index > Fetch the complete documentation index at: https://docs.gp.scale.com/llms.txt > Use this file to discover all available pages before exploring further. # Rank Chunks > ### Description Sorts a list of text chunks by similarity against a given query string. ### Details Use this API endpoint to rank which text chunks provide the most relevant responses to a given a query string. This is useful for stuffing chunks into a prompt where order may matter or for filtering out less relevant chunks according to the ranking strategy. For example, this API may be useful when doing retrieval augment generation (RAG). Sometimes vector store [similarity search]( https://scale-egp.readme.io/reference/query_vector_store) does not always return the best ranking of text chunks, since this is heavily dependent on embedding generation. This API endpoint can act as a post-processing step to re-sort the given chunks using more complex strategies that may outperform vector search, and then filter only the top-k most relevant chunks to stuff into the prompt for RAG. ### Restrictions and Limits Ranking can be a very intensive and slow process depending on methodology where duration scales with number of chunks. For best performance, we recommend ranking less than 640 chunks at a time, and you may see a decrease in performance as the number of chunks ranked increases. ## OpenAPI ````yaml https://app.stainlessapi.com/api/spec/documented/sgp/openapi.yml post /v4/chunks/rank openapi: 3.1.0 info: title: EGP API V4 description: >- This is the parent API for all EGP APIs. If you are looking for the EGP API, please go to https://api.egp.scale.com/docs. contact: name: Scale Generative AI Platform url: https://scale.com/genai-platform version: 0.1.0 servers: - url: https://api.egp.scale.com security: [] tags: - name: Models description: Model API. paths: /v4/chunks/rank: post: tags: - Chunks summary: Rank Chunks description: >- ### Description Sorts a list of text chunks by similarity against a given query string. ### Details Use this API endpoint to rank which text chunks provide the most relevant responses to a given a query string. This is useful for stuffing chunks into a prompt where order may matter or for filtering out less relevant chunks according to the ranking strategy. For example, this API may be useful when doing retrieval augment generation (RAG). Sometimes vector store [similarity search]( https://scale-egp.readme.io/reference/query_vector_store) does not always return the best ranking of text chunks, since this is heavily dependent on embedding generation. This API endpoint can act as a post-processing step to re-sort the given chunks using more complex strategies that may outperform vector search, and then filter only the top-k most relevant chunks to stuff into the prompt for RAG. ### Restrictions and Limits Ranking can be a very intensive and slow process depending on methodology where duration scales with number of chunks. For best performance, we recommend ranking less than 640 chunks at a time, and you may see a decrease in performance as the number of chunks ranked increases. operationId: POST-V4-/v2/chunks/rank requestBody: content: application/json: schema: $ref: '#/components/schemas/ChunksRankRequest' required: true responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ChunksRankResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' x-codeSamples: - lang: Python source: |- import os from scale_gp import SGPClient client = SGPClient( api_key=os.environ.get("SGP_API_KEY"), # This is the default and can be omitted ) ranked_chunks_response = client.chunks.rank( query="query", rank_strategy={ "method": "cross_encoder" }, relevant_chunks=[{ "chunk_id": "chunk_id", "score": 0, "text": "text", }], ) print(ranked_chunks_response.relevant_chunks) - lang: Go source: "package main\n\nimport (\n\t\"context\"\n\t\"fmt\"\n\n\t\"github.com/stainless-sdks/sgp-go\"\n\t\"github.com/stainless-sdks/sgp-go/option\"\n\t\"github.com/stainless-sdks/sgp-go/shared\"\n)\n\nfunc main() {\n\tclient := sgp.NewClient(\n\t\toption.WithAPIKey(\"My API Key\"),\n\t)\n\trankedChunksResponse, err := client.Chunks.Rank(context.TODO(), sgp.ChunkRankParams{\n\t\tQuery: sgp.F(\"query\"),\n\t\tRankStrategy: sgp.F[sgp.ChunkRankParamsRankStrategyUnion](sgp.ChunkRankParamsRankStrategyCrossEncoderRankStrategy{\n\t\t\tMethod: sgp.F(sgp.ChunkRankParamsRankStrategyCrossEncoderRankStrategyMethodCrossEncoder),\n\t\t}),\n\t\tRelevantChunks: sgp.F([]shared.ChunkParam{{\n\t\t\tChunkID: sgp.F(\"chunk_id\"),\n\t\t\tScore: sgp.F(0.000000),\n\t\t\tText: sgp.F(\"text\"),\n\t\t}}),\n\t})\n\tif err != nil {\n\t\tpanic(err.Error())\n\t}\n\tfmt.Printf(\"%+v\\n\", rankedChunksResponse.RelevantChunks)\n}\n" components: schemas: ChunksRankRequest: properties: query: type: string title: Query description: >- Natural language query to re-rank chunks against. If a vector store query was originally used to retrieve these chunks, please use the same query for this ranking relevant_chunks: items: $ref: '#/components/schemas/ChunkV2' type: array title: Relevant Chunks description: List of chunks to rank rank_strategy: $ref: '#/components/schemas/RankStrategy' description: >- The ranking strategy to use. Rank strategies determine how the ranking is done, They consist of the ranking method name and additional params needed to compute the ranking. Use the built-in `cross_encoder` or `rouge` strategies or create a custom one with the Models API. top_k: title: Top K description: >- Number of chunks to return. Must be greater than 0 if specified. If not specified, all chunks will be returned. type: integer exclusiveMinimum: 0 account_id: title: Account Id description: >- Account to rank chunks with. If you have access to more than one account, you must specify an account_id type: string type: object required: - query - relevant_chunks - rank_strategy title: ChunksRankRequest ChunksRankResponse: properties: relevant_chunks: items: $ref: '#/components/schemas/ChunkV2' type: array title: Relevant Chunks description: List of chunks ranked by the requested rank strategy type: object required: - relevant_chunks title: ChunksRankResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError ChunkV2: properties: chunk_id: type: string title: Chunk Id description: The unique ID of the chunk with embedding text: type: string title: Text description: The text associated with the chunk embedding: title: Embedding description: The vector embedding of the text associated with the chunk items: type: number type: array metadata: title: Metadata description: >- Any additional key value pairs of information stored by you on the chunk with embedding default: {} additionalProperties: true type: object user_supplied_metadata: title: User Supplied Metadata description: >- Any additional key value pairs of information returned from the custom chunking. default: {} additionalProperties: true type: object attachment_url: title: Attachment Url description: Original attachment URL from which this chunk got its data from type: string title: title: Title description: Title for this chunk, for example the file name type: string score: type: number title: Score description: >- A number between 0 and 1 representing how similar a chunk's embedding is to the query embedding. Higher numbers mean that this chunk with embedding is more similar. type: object required: - chunk_id - text - score title: ChunkV2 RankStrategy: oneOf: - $ref: '#/components/schemas/CrossEncoderRankStrategy' - $ref: '#/components/schemas/RougeRankStrategy' - $ref: '#/components/schemas/ModelRankStrategy' - $ref: '#/components/schemas/AzureAIFoundryRankStrategy' title: RankStrategy discriminator: propertyName: method mapping: azure_ai_foundry: $ref: '#/components/schemas/AzureAIFoundryRankStrategy' cross_encoder: $ref: '#/components/schemas/CrossEncoderRankStrategy' model: $ref: '#/components/schemas/ModelRankStrategy' rouge: $ref: '#/components/schemas/RougeRankStrategy' ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context additionalProperties: true type: object required: - loc - msg - type title: ValidationError CrossEncoderRankStrategy: properties: method: type: string const: cross_encoder title: Method description: The name of the rank strategy. Must be `cross_encoder`. default: cross_encoder params: $ref: '#/components/schemas/CrossEncoderRankParams' description: The parameters needed for ranking. default: cross_encoder_model: cross-encoder/ms-marco-MiniLM-L-12-v2 type: object title: CrossEncoderRankStrategy RougeRankStrategy: properties: method: type: string const: rouge title: Method description: The name of the rank strategy. default: rouge params: $ref: '#/components/schemas/RougeRankParams' description: The parameters needed for ranking. default: metric: rouge2 score: recall type: object title: RougeRankStrategy ModelRankStrategy: properties: method: type: string const: model title: Method description: Use a model from Models API for ranking. default: model params: $ref: '#/components/schemas/ModelRankParams' description: The parameters needed for ranking. default: model_params: {} type: object title: ModelRankStrategy AzureAIFoundryRankStrategy: properties: method: type: string const: azure_ai_foundry title: Method description: Use a model from Azure AI Foundry for ranking. default: azure_ai_foundry params: $ref: '#/components/schemas/AzureAIFoundryRankParams' description: The parameters needed for ranking. type: object required: - params title: AzureAIFoundryRankStrategy CrossEncoderRankParams: properties: cross_encoder_model: type: string enum: - cross-encoder/ms-marco-MiniLM-L-12-v2 - cross-encoder/mmarco-mMiniLMv2-L12-H384-v1 - Qwen/Qwen3-Reranker-0.6B - Qwen/Qwen3-Reranker-4B - Qwen/Qwen3-Reranker-8B title: Cross Encoder Model description: >- Cross encoder model to use when ranking. Supports [cross-encoder/ms-marco-MiniLM-L-12-v2](https://huggingface.co/cross-encoder/ms-marco-MiniLM-L-12-v2), [cross-encoder/mmarco-mMiniLMv2-L12-H384-v1](https://huggingface.co/cross-encoder/mmarco-mMiniLMv2-L12-H384-v1), [Qwen/Qwen3-Reranker-0.6B](https://huggingface.co/Qwen/Qwen3-Reranker-0.6B), [Qwen/Qwen3-Reranker-4B](https://huggingface.co/Qwen/Qwen3-Reranker-4B), and [Qwen/Qwen3-Reranker-8B](https://huggingface.co/Qwen/Qwen3-Reranker-8B). default: cross-encoder/ms-marco-MiniLM-L-12-v2 type: object title: CrossEncoderRankParams RougeRankParams: properties: metric: type: string title: Metric description: >- Rouge type, can be n-gram based (e.g. rouge1, rouge2) or longest common subsequence (rougeL or rougeLsum) default: rouge2 score: type: string enum: - precision - recall - fmeasure title: Score description: Metric to use from Rouge score default: recall type: object title: RougeRankParams ModelRankParams: properties: model_deployment_id: type: string title: Model Deployment Id description: The model deployment id of a custom model to use for reranking base_model_name: title: Base Model Name description: The name of a base model to use for reranking type: string model_params: title: Model Params additionalProperties: true type: object type: object title: ModelRankParams AzureAIFoundryRankParams: properties: endpoint_url: type: string title: Endpoint Url description: >- Azure AI Foundry model endpoint to use for reranking. Example url: https://cohere-rerank-v3-multilingual-xyz.eastus.models.ai.azure.com/v2/rerank endpoint_api_key: type: string title: Endpoint Api Key description: Azure AI Foundry Endpoint API key to use for reranking. type: object required: - endpoint_url - endpoint_api_key title: AzureAIFoundryRankParams ````