---
title: "Run a model with specified tools and messages."
method: POST
path: "/api/v1/{model_id}/run"
tags: ["model"]
---

# Run a model with specified tools and messages.

`POST /api/v1/{model_id}/run`

This endpoint runs a model with the specified tools and messages.

## Path parameters

- `model_id` string, required

## Query parameters

- `wait` boolean

## Request body

- object
  - `tools` ChatCompletionTool[] — A list of tools the model may call. Currently, only functions are supported as a tool. Use this to provide a list of functions the model may generate JSON inputs for. A max of 128 functions are supported.
    - `type` 'function', required — The type of the tool. Currently, only `function` is supported.
    - `function` FunctionObject, required
      - `description` string — A description of what the function does, used by the model to choose when and how to call the function.
      - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
      - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list.
  - `messages` object[], required
    - `role` 'system' | 'user' | 'assistant' | 'tool'
    - `content` string
  - `model` string, required
  - `stream` boolean, required
  - `temperature` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both.
  - `top_p` number, nullable — An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens comprising the top 10% probability mass are considered. We generally recommend altering this or `temperature` but not both.
  - `n` integer, nullable — How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs.
  - `max_tokens` integer, nullable — The maximum number of [tokens](/tokenizer) that can be generated in the chat completion. The total length of input tokens and generated tokens is limited by the model's context length. [Example Python code](https://cookbook.openai.com/examples/how_to_count_tokens_with_tiktoken) for counting tokens.
  - `tool_choice` union — Controls which (if any) tool is called by the model. `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools. Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. `none` is the default when no tools are present. `auto` is the default if tools are present.
    - 'none' | 'auto' | 'required' — `none` means the model will not call any tool and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools.
    - object
      - `type` 'function', required
      - `function` FunctionObject, required
        - `description` string — A description of what the function does, used by the model to choose when and how to call the function.
        - `name` string, required — The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        - `parameters` FunctionParameters — The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. Omitting `parameters` defines a function with an empty parameter list.

## Response `200`

Successful response

- ModelRunResponse
  - `id` string
  - `object` string
  - `created` integer
  - `model` string
  - `choices` object[]
    - `index` integer
    - `message` object
      - `role` string
      - `content` string
  - `usage` object
    - `prompt_tokens` integer
    - `completion_tokens` integer
    - `total_tokens` integer
  - `toolCalls` object[]
    - `functionName` string
    - `arguments` object
    - `response` object

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `500` — Internal Server Error

## Changes

- **2024-06-11** `56ef2faeac8e` — 1 info
  - api tag `model` added

[Change history](https://skmtc.dev/propulsion-ai/apis/propulsionai-api/changes/api/v1/:model_id/run/post.md)

---

[API](https://skmtc.dev/propulsion-ai/apis/propulsionai-api.md) · [All operations](https://skmtc.dev/propulsion-ai/apis/propulsionai-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/propulsion-ai/propulsionai-api/revisions/56ef2faeac8e/schema)