# Responses · tool calls

`POST /v1/responses` with your functions in `tools` lets the model ask for one: it answers with
a `function_call`, your code runs it, and the next request carries the result.

## Request

Send it with an API key, as JSON, like any request on the route: [Responses](/docs/reference/responses)
lists every field. [Tools and function calling](/docs/tools) walks through the same loop on
Chat.

### The tools

| Field | Needed | You send |
|---|---|---|
| `tools` | no | the functions the model may call, a list |
| `type` | yes | in each tool: `function` |
| `name` | yes | in each tool: the function's name, which the model's call repeats |
| `description` | no | in each tool: what it does and when to use it, for the model to read |
| `parameters` | no | in each tool: a JSON Schema for its arguments |
| `tool_choice` | no | `auto`, the model decides; `none`, no call; `required`, at least one call; or `{"type": "function", "name": ...}` to force one |
| `parallel_tool_calls` | no | `false` to have the model call one function at a time; else it may ask for several at once |

A request with `tools` goes to the model's providers that take tools. On a model none of whose
providers do, `tools` is ignored and the model answers in words.

Souk Bot lets the model check the stock before it answers:

```python
import json
import os
import urllib.request

API_KEY = os.environ["OPENDUNES_API_KEY"]
ADDRESS = "https://opendunes.com/v1/responses"
MODEL = "anthropic/claude-sonnet-4.5"
CHECK_STOCK = {
    "type": "function",
    "name": "check_stock",
    "description": "How many jackets of one size the Oran shop holds.",
    "parameters": {
        "type": "object",
        "properties": {"size": {"type": "string"}},
        "required": ["size"],
    },
}

request = urllib.request.Request(
    ADDRESS,
    data=json.dumps(
        {
            "model": MODEL,
            "input": "Do you have this jacket in size M?",
            "tools": [CHECK_STOCK],
        }
    ).encode(),
    headers={
        "Authorization": "Bearer " + API_KEY,
        "Content-Type": "application/json",
    },
)
with urllib.request.urlopen(request) as response:
    answer = json.load(response)

for item in answer["output"]:
    if item["type"] == "function_call":
        print(item["call_id"], item["name"], item["arguments"])
print(answer["usage"]["cost"])
```

```javascript
const API_KEY = process.env.OPENDUNES_API_KEY;
const ADDRESS = "https://opendunes.com/v1/responses";
const MODEL = "anthropic/claude-sonnet-4.5";
const CHECK_STOCK = {
  type: "function",
  name: "check_stock",
  description: "How many jackets of one size the Oran shop holds.",
  parameters: {
    type: "object",
    properties: { size: { type: "string" } },
    required: ["size"],
  },
};

const response = await fetch(ADDRESS, {
  method: "POST",
  headers: {
    Authorization: `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: MODEL,
    input: "Do you have this jacket in size M?",
    tools: [CHECK_STOCK],
  }),
});
const answer = await response.json();

for (const item of answer.output) {
  if (item.type === "function_call") {
    console.log(item.call_id, item.name, item.arguments);
  }
}
console.log(answer.usage.cost);
```

```go
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"net/http"
	"os"
)

const (
	address = "https://opendunes.com/v1/responses"
	model   = "anthropic/claude-sonnet-4.5"
)

func main() {
	apiKey := os.Getenv("OPENDUNES_API_KEY")
	checkStock := map[string]any{
		"type":        "function",
		"name":        "check_stock",
		"description": "How many jackets of one size the Oran shop holds.",
		"parameters": map[string]any{
			"type": "object",
			"properties": map[string]any{
				"size": map[string]string{"type": "string"},
			},
			"required": []string{"size"},
		},
	}

	body, err := json.Marshal(map[string]any{
		"model": model,
		"input": "Do you have this jacket in size M?",
		"tools": []any{checkStock},
	})
	if err != nil {
		panic(err)
	}

	req, err := http.NewRequest("POST", address, bytes.NewReader(body))
	if err != nil {
		panic(err)
	}
	req.Header.Set("Authorization", "Bearer "+apiKey)
	req.Header.Set("Content-Type", "application/json")

	res, err := http.DefaultClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer res.Body.Close()

	var answer struct {
		Output []struct {
			Type      string `json:"type"`
			CallID    string `json:"call_id"`
			Name      string `json:"name"`
			Arguments string `json:"arguments"`
		} `json:"output"`
		Usage struct {
			Cost json.Number `json:"cost"`
		} `json:"usage"`
	}
	if err := json.NewDecoder(res.Body).Decode(&answer); err != nil {
		panic(err)
	}

	for _, item := range answer.Output {
		if item.Type == "function_call" {
			fmt.Println(item.CallID, item.Name, item.Arguments)
		}
	}
	fmt.Println(answer.Usage.Cost)
}
```

```bash cURL
ADDRESS="https://opendunes.com/v1/responses"
MODEL="anthropic/claude-sonnet-4.5"

curl "$ADDRESS" \
  -H "Authorization: Bearer $OPENDUNES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$MODEL"'",
    "input": "Do you have this jacket in size M?",
    "tools": [
      {
        "type": "function",
        "name": "check_stock",
        "description": "How many jackets of one size the Oran shop holds.",
        "parameters": {
          "type": "object",
          "properties": {"size": {"type": "string"}},
          "required": ["size"]
        }
      }
    ]
  }'
```

### The next turn

The route keeps nothing between requests. Your code runs the function, then sends the whole
conversation again with two more items in `input`: the model's call, as it came, and your
result. The model then writes its reply.

| Field | Needed | You send |
|---|---|---|
| `function_call` | yes | the item the model answered with, as it came |
| `function_call_output` | yes | an item for each call: `{"type": "function_call_output", "call_id": ..., "output": ...}` |
| `call_id` | yes | in the output: the `call_id` of the call it answers |
| `output` | yes | in the output: the result, a string, or a list of `input_text`, `input_image` and `input_file` parts, where the model reads them |

Souk Bot's second request, illustrative:

```json
{
  "model": "anthropic/claude-sonnet-4.5",
  "input": [
    {"role": "user", "content": "Do you have this jacket in size M?"},
    {
      "type": "function_call",
      "call_id": "toolu_01A9",
      "name": "check_stock",
      "arguments": "{\"size\": \"M\"}"
    },
    {
      "type": "function_call_output",
      "call_id": "toolu_01A9",
      "output": "{\"size\": \"M\", \"in_stock\": 4}"
    }
  ],
  "tools": [{"type": "function", "name": "check_stock"}]
}
```

## Response

`200 OK`. When the model calls a function, `output` holds a `function_call` item and `status`
is `completed`: the turn is the model's request to you. Illustrative:

```json
{
  "type": "function_call",
  "id": "fc_7c3a91e4",
  "call_id": "toolu_01A9",
  "name": "check_stock",
  "arguments": "{\"size\": \"M\"}",
  "status": "completed"
}
```

| Field | Holds |
|---|---|
| `type` | `function_call` |
| `id` | the item's id |
| `call_id` | the call's id, which your `function_call_output` repeats |
| `name` | the function the model calls, one of your `tools` |
| `arguments` | its arguments, a JSON string that follows your `parameters` schema; parse it before use |
| `status` | `completed` once the arguments are whole |

Several calls in one turn are several `function_call` items, each with its own `call_id`: run
them all and send every result back.

**With `stream: true`.** `response.output_item.added` opens the `function_call` item,
`response.function_call_arguments.delta` carries each next piece of its arguments,
`response.function_call_arguments.done` the whole of them, and `response.completed` ends the
stream with `usage`, `cost` among it.

## What it cost

Charged in DA from your balance on each request: the tokens the model reports, at the model's
rates, which its model page shows. `usage.cost` carries the charge. A call and its result take
two requests, each charged.

- **Moves the count**: `tools`, whose definitions are sent as input on every turn; the
  `function_call` and `function_call_output` items sent back, counted as input; the call the
  model writes, counted as output.
- **Changes the answer, never the bill**: `tool_choice` and `parallel_tool_calls`.

Running your function costs nothing here: it runs in your code.

## Errors

An error keeps the Responses shape: [Responses · errors](/docs/reference/responses-errors)
lists every status and every word.

| Status | When |
|---|---|
| 400 | a tool has no `type` or `name`, a field has the wrong type, or the provider refused a tool or a result, such as one whose `call_id` matches no call in `input` |
| 401 | the key is missing, wrong, disabled or expired |
| 402 | your balance is at zero or below, cannot pay the request's hold, or the key's cap is spent; `metadata.limit_source`, beside `error`, names which, and `deposit_url` or `key_url` there says where to lift it. After up to 60 seconds of waiting for money your running requests hold, the 402 carries `Retry-After: 60` |
| 404 | `model` is not a model on sale |
