> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Router.Rerank SDK Reference

> Rerank documents by relevance to a query through the AI Gateway using the Node.js and Python SDKs, powering better RAG retrieval results.

## Router.Rerank

### Create a Rerank

Rerank a list of documents based on their relevance to a query.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.router.rerank.create(query="<value>", documents=[
          "<value 1>",
      ], model="cohere/rerank-v4.0-pro", retry={
          "on_codes": [
              429,
              500,
              502,
              503,
              504,
          ],
      }, cache={
          "ttl": 3600,
          "type": "exact_match",
      }, load_balancer={
          "type": "weight_based",
          "models": [],
      }, timeout={
          "call_timeout": 30000,
      }, orq={
          "fallbacks": [
              {
                  "model": "openai/gpt-5.6-luna",
              },
          ],
          "cache": {
              "ttl": 3600,
              "type": "exact_match",
          },
          "retry": {
              "on_codes": [
                  429,
                  500,
                  502,
                  503,
                  504,
              ],
          },
          "identity": {
              "id": "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
              "display_name": "Jane Doe",
              "email": "jane.doe@example.com",
              "metadata": [
                  {
                      "department": "Engineering",
                      "role": "Senior Developer",
                  },
              ],
              "logo_url": "https://example.com/avatars/jane-doe.jpg",
              "tags": [
                  "hr",
                  "engineering",
              ],
          },
          "load_balancer": {
              "type": "weight_based",
              "models": [
                  {
                      "model": "openai/gpt-6-astra",
                      "weight": 0.7,
                  },
                  {
                      "model": "anthropic/claude-sonnet-5",
                      "weight": 0.3,
                  },
              ],
          },
          "timeout": {
              "call_timeout": 30000,
          },
      })

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.router.rerank.create({
      query: "<value>",
      documents: [
        "<value 1>",
      ],
      model: "cohere/rerank-v4.0-pro",
      retry: {
        onCodes: [
          429,
          500,
          502,
          503,
          504,
        ],
      },
      cache: {
        ttl: 3600,
        type: "exact_match",
      },
      loadBalancer: {
        type: "weight_based",
        models: [],
      },
      timeout: {
        callTimeout: 30000,
      },
      orq: {
        fallbacks: [
          {
            model: "openai/gpt-5.6-luna",
          },
        ],
        cache: {
          ttl: 3600,
          type: "exact_match",
        },
        retry: {
          onCodes: [
            429,
            500,
            502,
            503,
            504,
          ],
        },
        identity: {
          id: "contact_01ARZ3NDEKTSV4RRFFQ69G5FAV",
          displayName: "Jane Doe",
          email: "jane.doe@example.com",
          metadata: [
            {
              "department": "Engineering",
              "role": "Senior Developer",
            },
          ],
          logoUrl: "https://example.com/avatars/jane-doe.jpg",
          tags: [
            "hr",
            "engineering",
          ],
        },
        loadBalancer: {
          type: "weight_based",
          models: [
            {
              model: "openai/gpt-6-astra",
              weight: 0.7,
            },
            {
              model: "anthropic/claude-sonnet-5",
              weight: 0.3,
            },
          ],
        },
        timeout: {
          callTimeout: 30000,
        },
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "query": str,  # required
        "documents": List[str],  # required
        "model": str,  # required
        "top_n": Optional[int],
        "return_documents": Optional[bool],
        "filename": Optional[str],
        "name": Optional[str],
        "fallbacks": [{  # optional
            "model": str,  # required
        }],
        "retry": {  # optional
            "count": Optional[float],
            "on_codes": List[float],  # optional
        },
        "cache": {  # optional
            "ttl": Optional[float],
            "type": Literal["exact_match"],  # required
        },
        "load_balancer": Union[CreateRerankLoadBalancer1],  # optional
        "timeout": {  # optional
            "call_timeout": float,  # required
        },
        "plugins": [{  # optional
            "id": Literal["pii_redaction"],  # required
            "language": Optional[str],
            "regions": List[str],  # optional
            "entities": List[str],  # optional
            "entity_thresholds": Dict[str, float],  # optional
            "threshold": Optional[float],
            "on_failure": Optional[Literal["block", "passthrough"]],
        }],
        "orq": {  # optional
            "name": Optional[str],
            "fallbacks": [{  # optional
                "model": str,  # required
            }],
            "cache": {  # optional
                "ttl": Optional[float],
                "type": Literal["exact_match"],  # required
            },
            "retry": {  # optional
                "count": Optional[float],
                "on_codes": List[float],  # optional
            },
            "identity": {  # optional
                "id": str,  # required
                "display_name": Optional[str],
                "email": Optional[str],
                "metadata": List[Dict[str, Any]],  # optional
                "logo_url": Optional[str],
                "tags": List[str],  # optional
            },
            "contact": {  # optional
                "id": str,  # required
                "display_name": Optional[str],
                "email": Optional[str],
                "metadata": List[Dict[str, Any]],  # optional
                "logo_url": Optional[str],
                "tags": List[str],  # optional
            },
            "load_balancer": Union[CreateRerankLoadBalancerRouterRerank1],  # optional
            "timeout": {  # optional
                "call_timeout": float,  # required
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      query: string;  // required
      documents: string[];  // required
      model: string;  // required
      topN?: number;
      returnDocuments?: boolean;
      filename?: string;
      name?: string;
      fallbacks?: {
        model: string;  // required
      }[];
      retry?: {
        count?: number;
        onCodes?: number[];
      };
      cache?: {
        ttl?: number;
        type: "exact_match";  // required
      };
      loadBalancer?: CreateRerankLoadBalancer1;
      timeout?: {
        callTimeout: number;  // required
      };
      plugins?: {
        id: "pii_redaction";  // required
        language?: string;
        regions?: string[];
        entities?: string[];
        entityThresholds?: Record<string, number>;
        threshold?: number;
        onFailure?: "block" | "passthrough";
      }[];
      orq?: {
        name?: string;
        fallbacks?: {
          model: string;  // required
        }[];
        cache?: {
          ttl?: number;
          type: "exact_match";  // required
        };
        retry?: {
          count?: number;
          onCodes?: number[];
        };
        identity?: {
          id: string;  // required
          displayName?: string;
          email?: string;
          metadata?: Record<string, any>[];
          logoUrl?: string;
          tags?: string[];
        };
        contact?: {
          id: string;  // required
          displayName?: string;
          email?: string;
          metadata?: Record<string, any>[];
          logoUrl?: string;
          tags?: string[];
        };
        loadBalancer?: CreateRerankLoadBalancerRouterRerank1;
        timeout?: {
          callTimeout: number;  // required
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": Optional[str],
        "object": Literal["list"],
        "results": [{
            "object": Literal["rerank"],
            "index": float,
            "relevance_score": float,
            "document": {  # optional
                "text": str,
            },
        }],
        "usage": {  # optional
            "total_tokens": float,
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id?: string;
      object: "list";
      results: {
        object: "rerank";
        index: number;
        relevanceScore: number;
        document?: {
          text: string;
        };
      }[];
      usage?: {
        totalTokens: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.