---
title: "Get Rank Of Best Models For Payload"
method: POST
path: "/v1/models/rank"
tags: ["models"]
---

# Get Rank Of Best Models For Payload

`POST /v1/models/rank`

## Request body

- CompletionRequestPayload — Used after validation is completed -- therefore no validation required here
  - `model` string, nullable — https://docs.pulze.ai/overview/models Specify the model you'd like Pulze to use. (optional). Can be the full model name, or a subset for multi-matching. Defaults to our dynamic routing, i.e. best model for this request.
  - `max_tokens` integer, nullable — The maximum number of tokens that the response can contain.
  - `temperature` number, nullable — Optionally specify the temperature for this request only. Leave empty to allow Pulze to guess it for you.
  - `top_p` number, nullable — https://octo.ai/docs/text-gen-solution/rest-api#input-parameters A value between 0.0 and 1.0 that controls the probability of the model generating a particular token.
  - `tools` ToolFunctionInput[], nullable
    - `type` 'function'
    - `function` ToolFunctionDetail, required
      - `name` string, required — A unique name for the function
      - `description` string, nullable — A description of the function. Might help the LLM to figure out the structure and parameters
      - `parameters` FunctionParameters, required
        - `type` string — Following JSON schema, this must be 'object'.
        - `properties` object, required — JSON schema's properties
        - `required` string[], nullable, required — List of required parameters
  - `tool_choice` union
    - 'none' | 'auto'
    - ToolChoice
      - `type` 'function' | 'json_object', nullable — (Note: Not supported by all models yet) // `json_object`: If you instruct the model to return a JSON object, the model will respond in a valid JSON format. || `function`: If you set this to function, you must also pass the `function` parameter with extra information. ||
      - `function` ToolChoiceFunction
        - `name` string, required — The name of the function you'd like the code to call
  - `n` integer, nullable — How many completions to generate for each prompt. @default 1
  - `stream` boolean, nullable — Specify if you want the response to be streamed or to be returned as a standard HTTP request. Currently we only support streaming for OpenAI-compatible models.
  - `logprobs` integer, nullable — COMING SOON https://platform.openai.com/docs/api-reference/completions/create#completions/create-logprobs Include the log probabilities on the logprobs most likely tokens, as well the chosen tokens.
  - `stop` union — Stop responding when this sequence of characters is generated. Leave empty to allow the model to decide.
    - string
    - string[]
  - `presence_penalty` number, nullable — https://platform.openai.com/docs/api-reference/completions/create#completions/create-presence_penalty Increase the model's likelihood to talk about new topics
  - `frequency_penalty` number, nullable — https://platform.openai.com/docs/api-reference/completions/create#completions/create-frequency_penalty Increase the model's likelihood to not repeat tokens/words
  - `best_of` integer, nullable — The number of responses to _generate_. Out of those, it will return the best `n`.
  - `logit_bias` object, nullable — COMING SOON https://platform.openai.com/docs/api-reference/completions/create#completions/create-logit_bias Modify the likelihood of specified tokens appearing in the completion. See here for a detailed explanation on how to use: https://help.openai.com/en/articles/5247780-using-logit-bias-to-define-token-probability
  - `response_format` RequestResponseFormat
    - `type` 'text' | 'json_object', required
  - `messages` RoleContentChatChoiceInput[], nullable
    - `role` 'user' | 'assistant' | 'system', required
    - `content` union, required
      - string
      - RoleContentChatChoiceContent[]
        - `type` 'text' | 'image_url', required
        - `text` string, nullable
        - `image_url` RoleContentChatChoiceContentImageUrl
          - `url` string, required
    - `tool_calls` ToolCall[], nullable — If `tool_choice` parameter was passed, and the model supports it, this will return a list of the different calls/functions used.
      - `function` FunctionCallArguments, required
        - `arguments` string, required — A stringified JSON that represents the arguments for the function
        - `name` string, required — The name of the function to which the arguments correspond
      - `id` string, required
      - `type` 'function'
  - `assistant_id` string, uuid, nullable — The Assistant ID to use for this request
  - `assistant_version_id` string, uuid, nullable — The Assistant version ID to use for this request
  - `conversation_id` string, uuid, nullable — The Conversation ID to use for this request
  - `parent_request_id` string, uuid, nullable — The Parent Request ID to use for this request
  - `plugins` string[] — The list of plugins to enable for the request
  - `images` string[], nullable — Images to be analyzed
  - `files` string[], nullable — A list of file urls that should be included. Images, audio, etc.

## Response `200`

Successful Response

- PulzeEngineModelRanking
  - `models` PulzeModelWithScore[] — A list of the best models for the given prompt+config, sorted by overall score descending.
    - `model` string, required — The name of the model. Can belong to many providers
    - `provider` string, nullable — The provider for the model.
    - `owner` string, nullable — The owner of the model. Sometimes, for a provider/model combination, many instances exist, trained on different data
    - `namespace` string, required — The fully qualified (namespaced) model name
    - `at` string, nullable — Extra model settings inferred from namespace
    - `score` number, nullable, required
    - `quality` number, nullable, required
    - `latency` number, nullable, required
    - `cost` number, nullable, required
    - `is_scored` boolean
  - `hits` PromptNeighbors[], nullable — A list of most similar scored prompts if any
    - `id` string, required
    - `category` string, required
    - `similarity` number, required

## Other responses

- `422` — Validation Error

---

[API](https://skmtc.net/pulze/apis/pulze-ai-api.md) · [All operations](https://skmtc.net/pulze/apis/pulze-ai-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pulze/pulze-ai-api/revisions/a5e0b539abc5/schema)