Responses Endpoints

Responses API, currently in public preview.

Create a response

POST /v1/responses#

AdditionalProperties#

map<any>

background#

boolean

Default Value: false

Must be false. The response is generated during the request.

conversation#

any|null

Must be omitted or null. Keep conversation history in your application and send it in input.

input#

A text prompt or an array of messages, prior output items, and function results. For a multi-turn conversation, include the conversation history in this array. Images and files can be included in user messages and function results; support depends on the model.

instructions#

string|null

Instructions for the model, added before the messages in input.

max_output_tokens#

integer|null

The maximum number of tokens to generate, including reasoning tokens and answer text.

max_tool_calls#

integer|null

Accepted for compatibility; currently ignored.

metadata#

map<string>|null

String key-value pairs associated with the request.

model#

*string

The ID of the model to use. See Models for available models and their capabilities.

moderation#

any|null

Must be omitted or null.

parallel_tool_calls#

boolean

Default Value: true

Whether the model can return multiple function calls in one response.

previous_response_id#

any|null

Must be omitted or null. This API is stateless; include prior output items in input.

prompt#

any|null

Must be omitted or null. Send your prompt in input and instructions.

prompt_cache_key#

string|null

A key used for prompt cache routing.

reasoning#

ResponsesSupportedReasoning|null

The reasoning effort to use. Choose an effort supported by the model; see Reasoning.

store#

boolean|null

Must be omitted, false, or null. Responses are stateless.

stream#

boolean

Default Value: false

Set to true to receive Server-Sent Events as the response is generated. In the Mistral SDKs, each frame contains an event in data.

temperature#

number|null

Controls sampling randomness. Lower values produce more consistent output. When omitted, the model's default is used.

text#

ResponsesTextConfig|null

Configure text output with format: plain text, JSON mode, or a JSON Schema.

tool_choice#

"none"|"auto"|"required"|ResponsesToolChoiceFunction

Controls function calling: "auto" lets the model decide, "none" disables calls, and "required" requires a function call. You can also select a function by name.

tools#

array<ResponsesFunctionTool|ResponsesNamespaceTool>

Function definitions that the model can call, optionally grouped into namespaces. Your application executes each function and sends its result in a later request.

top_logprobs#

integer|null

Must be omitted, 0, or null.

top_p#

number|null

Nucleus sampling threshold. When omitted, the model's default is used.

truncation#

string

Default Value: "disabled"

Must be "disabled". Keep the input within the model's context window.

200 (application/json)

200 (text/event-stream)

Successful Response

AdditionalProperties#

map<any>

background#

boolean|null

completed_at#

number|null

created_at#

*number

error#

ResponsesError|null

Error details when generation fails.

id#

*string

incomplete_details#

ResponsesIncompleteDetails|null

Details when generation stops before the response is complete.

instructions#

string|null

max_output_tokens#

integer|null

max_tool_calls#

integer|null

metadata#

map<string>|null

model#

*string

object#

*string

output#

*array<ResponsesOutputMessage|ResponsesFunctionToolCall|ResponsesReasoningItem>

The generated messages, reasoning items, and function calls. To continue the conversation, append these items to your next request's input.

parallel_tool_calls#

*boolean

previous_response_id#

string|null

prompt_cache_key#

string|null

prompt_cache_retention#

"in_memory"|"24h"

reasoning#

ResponsesSupportedReasoning|null

safety_identifier#

string|null

service_tier#

"auto"|"default"|"flex"|"scale"|"priority"

status#

The response status. Check this field to see whether generation completed.

temperature#

number|null

top_logprobs#

integer|null

top_p#

number|null

truncation#

"auto"|"disabled"

usage#

ResponsesUsage|null

Token usage for this response.

user#

string|null

curl https://api.mistral.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
  "model": "mistral-large-4",
  "input": "Write a one-sentence greeting.",
  "reasoning": {
    "effort": "high"
  },
  "max_output_tokens": 4096
}'

curl https://api.mistral.ai/v1/responses \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
  "model": "mistral-large-4",
  "input": "Write a one-sentence greeting.",
  "reasoning": {
    "effort": "high"
  },
  "max_output_tokens": 4096
}'

import os
from mistralai.client import Mistral

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    response = client.responses.create(
        model="mistral-large-4",
        input="Write a one-sentence greeting.",
        reasoning={"effort": "high"},
        max_output_tokens=4096,
    )

    for item in response.output:
        if item.type == "message":
            for part in item.content:
                if part.type == "output_text":
                    print(part.text)

import os
from mistralai.client import Mistral

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    response = client.responses.create(
        model="mistral-large-4",
        input="Write a one-sentence greeting.",
        reasoning={"effort": "high"},
        max_output_tokens=4096,
    )

    for item in response.output:
        if item.type == "message":
            for part in item.content:
                if part.type == "output_text":
                    print(part.text)

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.responses.create({
  model: "mistral-large-4",
  input: "Write a one-sentence greeting.",
  reasoning: { effort: "high" },
  maxOutputTokens: 4096,
});

for (const item of response.output) {
  if (item.type === "message") {
    for (const part of item.content) {
      if (part.type === "output_text") console.log(part.text);
    }
  }
}

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.responses.create({
  model: "mistral-large-4",
  input: "Write a one-sentence greeting.",
  reasoning: { effort: "high" },
  maxOutputTokens: 4096,
});

for (const item of response.output) {
  if (item.type === "message") {
    for (const part of item.content) {
      if (part.type === "output_text") console.log(part.text);
    }
  }
}

200 (application/json)

200 (text/event-stream)

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1792584000,
  "model": "mistral-large-4",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_example",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "tool_choice": "auto",
  "tools": [],
  "store": false,
  "error": null,
  "incomplete_details": null,
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 10,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 22
  }
}

{
  "id": "resp_example",
  "object": "response",
  "created_at": 1792584000,
  "model": "mistral-large-4",
  "status": "completed",
  "output": [
    {
      "type": "message",
      "id": "msg_example",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Hello! How can I help you today?",
          "annotations": []
        }
      ]
    }
  ],
  "parallel_tool_calls": true,
  "tool_choice": "auto",
  "tools": [],
  "store": false,
  "error": null,
  "incomplete_details": null,
  "usage": {
    "input_tokens": 12,
    "input_tokens_details": {
      "cached_tokens": 0
    },
    "output_tokens": 10,
    "output_tokens_details": {
      "reasoning_tokens": 0
    },
    "total_tokens": 22
  }
}

Count input tokens

POST /v1/responses/input_tokens#

Count response input tokens.

Count the input tokens for a Responses request without generating a response. The count includes the supplied conversation, instructions, and tool definitions.

Use the same input, instructions, and tools that you plan to send when creating a response. For multi-turn conversations, include prior output items and function results in input.

200

Successful Response

AdditionalProperties#

map<any>

input_tokens#

*integer

The number of input tokens, including conversation history, instructions, and tool definitions.

object#

*string

curl https://api.mistral.ai/v1/responses/input_tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
  "model": "mistral-large-4",
  "input": "Write a one-sentence greeting."
}'

curl https://api.mistral.ai/v1/responses/input_tokens \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $MISTRAL_API_KEY" \
  -d '{
  "model": "mistral-large-4",
  "input": "Write a one-sentence greeting."
}'

import os
from mistralai.client import Mistral

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    response = client.responses.count_input_tokens(
        model="mistral-large-4",
        input="Write a one-sentence greeting.",
    )

    print(response.input_tokens)

import os
from mistralai.client import Mistral

with Mistral(api_key=os.environ["MISTRAL_API_KEY"]) as client:
    response = client.responses.count_input_tokens(
        model="mistral-large-4",
        input="Write a one-sentence greeting.",
    )

    print(response.input_tokens)

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.responses.countInputTokens({
  model: "mistral-large-4",
  input: "Write a one-sentence greeting.",
});

console.log(response.inputTokens);

import { Mistral } from "@mistralai/mistralai";

const client = new Mistral({ apiKey: process.env.MISTRAL_API_KEY });

const response = await client.responses.countInputTokens({
  model: "mistral-large-4",
  input: "Write a one-sentence greeting.",
});

console.log(response.inputTokens);

200

{
  "object": "response.input_tokens",
  "input_tokens": 12
}

{
  "object": "response.input_tokens",
  "input_tokens": 12
}

Responses Endpoints

Examples

POST /v1/responses#

Request Body#

AdditionalProperties#

background#

conversation#

input#

instructions#

max_output_tokens#

max_tool_calls#

metadata#

model#

moderation#

parallel_tool_calls#

previous_response_id#

prompt#

prompt_cache_key#

reasoning#

store#

stream#

temperature#

text#

tool_choice#

tools#

top_logprobs#

top_p#

truncation#

AdditionalProperties#

background#

completed_at#

created_at#

error#

id#

incomplete_details#

instructions#

max_output_tokens#

max_tool_calls#

metadata#

model#

object#

output#

parallel_tool_calls#

previous_response_id#

prompt_cache_key#

prompt_cache_retention#

reasoning#

safety_identifier#

service_tier#

status#

temperature#

text#

tool_choice#

tools#

top_logprobs#

top_p#

truncation#

usage#

user#

ResponsesStreamFrame#

POST /v1/responses/input_tokens#

Request Body#

AdditionalProperties#

conversation#

input#

instructions#

model#

parallel_tool_calls#

previous_response_id#

prompt#

reasoning#

text#

tool_choice#

tools#

truncation#

AdditionalProperties#

input_tokens#

object#