0
# Responses API
1

2
Create responses with advanced tool support including computer use, file search, and code patching. The Responses API provides an enhanced interface for complex assistant interactions.
3

4
## Capabilities
5

6
### Create Response
7

8
Generate a response with advanced tools and capabilities.
9

10
```python { .api }
11
def create(
12
    self,
13
    *,
14
    model: str,
15
    input: dict | list[dict],
16
    instructions: str | Omit = omit,
17
    metadata: dict[str, str] | Omit = omit,
18
    parallel_tool_calls: bool | Omit = omit,
19
    reasoning_effort: str | Omit = omit,
20
    store: bool | Omit = omit,
21
    stream: bool | Omit = omit,
22
    temperature: float | Omit = omit,
23
    tool_choice: str | dict | Omit = omit,
24
    tools: list[dict] | Omit = omit,
25
    top_p: float | Omit = omit,
26
    extra_headers: dict[str, str] | None = None,
27
    extra_query: dict[str, object] | None = None,
28
    extra_body: dict[str, object] | None = None,
29
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
30
) -> Response:
31
    """
32
    Create a response with advanced tools.
33

34
    Args:
35
        model: Model ID to use.
36

37
        input: Input message(s). Can be:
38
            - Single message: {"role": "user", "content": "..."}
39
            - List of messages: [{"role": "user", "content": "..."}, ...]
40

41
        instructions: System instructions for the response.
42

43
        metadata: Key-value pairs (max 16).
44

45
        parallel_tool_calls: Enable parallel tool execution.
46

47
        reasoning_effort: Reasoning level for reasoning models.
48

49
        store: If true, store response for later retrieval.
50

51
        stream: Enable streaming response.
52

53
        temperature: Sampling temperature.
54

55
        tool_choice: Tool choice configuration.
56

57
        tools: Available tools. Options:
58
            - {"type": "function", "function": {...}}: Custom functions
59
            - {"type": "file_search"}: File search
60
            - {"type": "computer_use"}: Computer use (screen/keyboard/mouse)
61
            - {"type": "apply_patch"}: Code patching
62

63
        top_p: Nucleus sampling.
64

65
    Returns:
66
        Response: Generated response with tool results.
67
    """
68
```
69

70
Usage examples:
71

72
```python
73
from openai import OpenAI
74

75
client = OpenAI()
76

77
# Basic response
78
response = client.responses.create(
79
    model="gpt-4",
80
    input={"role": "user", "content": "Hello!"}
81
)
82

83
print(response.output[0].content)
84

85
# With file search
86
response = client.responses.create(
87
    model="gpt-4",
88
    input={"role": "user", "content": "Find information about Python."},
89
    tools=[{"type": "file_search"}]
90
)
91

92
# With computer use (beta)
93
response = client.responses.create(
94
    model="gpt-4",
95
    input={"role": "user", "content": "Click the button."},
96
    tools=[{
97
        "type": "computer_use",
98
        "display_width_px": 1920,
99
        "display_height_px": 1080
100
    }]
101
)
102

103
# With code patching
104
response = client.responses.create(
105
    model="gpt-4",
106
    input={"role": "user", "content": "Fix the bug in this code."},
107
    tools=[{"type": "apply_patch"}]
108
)
109

110
# Multi-turn conversation
111
messages = [
112
    {"role": "user", "content": "What is 2+2?"},
113
    {"role": "assistant", "content": "4"},
114
    {"role": "user", "content": "What about 3+3?"}
115
]
116

117
response = client.responses.create(
118
    model="gpt-4",
119
    input=messages
120
)
121

122
# Streaming response
123
stream = client.responses.create(
124
    model="gpt-4",
125
    input={"role": "user", "content": "Tell me a story."},
126
    stream=True
127
)
128

129
for chunk in stream:
130
    if chunk.delta:
131
        print(chunk.delta.content, end="", flush=True)
132
```
133

134
### Retrieve Response
135

136
Get a stored response by ID.
137

138
```python { .api }
139
def retrieve(
140
    self,
141
    response_id: str,
142
    *,
143
    extra_headers: dict[str, str] | None = None,
144
    extra_query: dict[str, object] | None = None,
145
    extra_body: dict[str, object] | None = None,
146
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
147
) -> Response:
148
    """Retrieve a stored response."""
149
```
150

151
### Delete Response
152

153
Delete a stored response by ID.
154

155
```python { .api }
156
def delete(
157
    self,
158
    response_id: str,
159
    *,
160
    extra_headers: dict[str, str] | None = None,
161
    extra_query: dict[str, object] | None = None,
162
    extra_body: dict[str, object] | None = None,
163
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
164
) -> None:
165
    """
166
    Delete a response with the given ID.
167

168
    Args:
169
        response_id: The ID of the response to delete.
170
    """
171
```
172

173
### Cancel Response
174

175
Cancel an in-progress response.
176

177
```python { .api }
178
def cancel(
179
    self,
180
    response_id: str,
181
    *,
182
    extra_headers: dict[str, str] | None = None,
183
    extra_query: dict[str, object] | None = None,
184
    extra_body: dict[str, object] | None = None,
185
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
186
) -> Response:
187
    """
188
    Cancel an in-progress response.
189

190
    Only responses created with the `background` parameter set to `true` can be cancelled.
191

192
    Args:
193
        response_id: The ID of the response to cancel.
194
    """
195
```
196

197
### Stream Response
198

199
Stream a response in real-time, either creating a new response or streaming an existing one.
200

201
```python { .api }
202
def stream(
203
    self,
204
    *,
205
    response_id: str = omit,
206
    input: str | dict | list[dict] | None = omit,
207
    model: str | None = omit,
208
    background: bool | None = omit,
209
    text_format: type = omit,
210
    tools: list[dict] | None = omit,
211
    conversation: dict | None = omit,
212
    include: list[str] | None = omit,
213
    instructions: str | None = omit,
214
    max_output_tokens: int | None = omit,
215
    max_tool_calls: int | None = omit,
216
    metadata: dict[str, str] | None = omit,
217
    parallel_tool_calls: bool | None = omit,
218
    previous_response_id: str | None = omit,
219
    prompt: dict | None = omit,
220
    prompt_cache_key: str | None = omit,
221
    prompt_cache_retention: Literal["in-memory", "24h"] | None = omit,
222
    reasoning: dict | None = omit,
223
    safety_identifier: str | None = omit,
224
    service_tier: Literal["auto", "default", "flex", "scale", "priority"] | None = omit,
225
    store: bool | None = omit,
226
    stream_options: dict | None = omit,
227
    temperature: float | None = omit,
228
    text: dict | None = omit,
229
    tool_choice: str | dict | None = omit,
230
    top_logprobs: int | None = omit,
231
    top_p: float | None = omit,
232
    truncation: Literal["auto", "disabled"] | None = omit,
233
    user: str | None = omit,
234
    starting_after: int | None = omit,
235
    extra_headers: dict[str, str] | None = None,
236
    extra_query: dict[str, object] | None = None,
237
    extra_body: dict[str, object] | None = None,
238
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
239
) -> ResponseStreamManager:
240
    """
241
    Stream a response. Can either create a new response or stream an existing one.
242

243
    Args:
244
        response_id: If provided, stream an existing response. Otherwise, create a new response.
245
        input: Input message(s) for creating a new response.
246
        model: Model ID to use for creating a new response.
247
        text_format: Parse streaming text into a specific format type.
248
        starting_after: For streaming existing responses, start streaming after this item index.
249

250
    Returns:
251
        ResponseStreamManager: Streaming response manager for iterating over chunks.
252
    """
253
```
254

255
### Parse Response
256

257
Create a response with structured output parsing using a format type.
258

259
```python { .api }
260
def parse(
261
    self,
262
    *,
263
    text_format: type,
264
    background: bool | None = omit,
265
    conversation: dict | None = omit,
266
    include: list[str] | None = omit,
267
    input: str | dict | list[dict] | None = omit,
268
    instructions: str | None = omit,
269
    max_output_tokens: int | None = omit,
270
    max_tool_calls: int | None = omit,
271
    metadata: dict[str, str] | None = omit,
272
    model: str | None = omit,
273
    parallel_tool_calls: bool | None = omit,
274
    previous_response_id: str | None = omit,
275
    prompt: dict | None = omit,
276
    prompt_cache_key: str | None = omit,
277
    prompt_cache_retention: Literal["in-memory", "24h"] | None = omit,
278
    reasoning: dict | None = omit,
279
    safety_identifier: str | None = omit,
280
    service_tier: Literal["auto", "default", "flex", "scale", "priority"] | None = omit,
281
    store: bool | None = omit,
282
    stream: Literal[False] | Literal[True] | None = omit,
283
    stream_options: dict | None = omit,
284
    temperature: float | None = omit,
285
    text: dict | None = omit,
286
    tool_choice: str | dict | None = omit,
287
    tools: list[dict] | None = omit,
288
    top_logprobs: int | None = omit,
289
    top_p: float | None = omit,
290
    truncation: Literal["auto", "disabled"] | None = omit,
291
    user: str | None = omit,
292
    verbosity: Literal["low", "medium", "high"] | None = omit,
293
    extra_headers: dict[str, str] | None = None,
294
    extra_query: dict[str, object] | None = None,
295
    extra_body: dict[str, object] | None = None,
296
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
297
) -> ParsedResponse:
298
    """
299
    Create a response with structured output parsing.
300

301
    Args:
302
        text_format: A type (Pydantic model or similar) to parse the response into.
303
        input: Input message(s).
304
        model: Model ID to use.
305

306
    Returns:
307
        ParsedResponse: Response with parsed structured output.
308
    """
309
```
310

311
### Input Items
312

313
List input items for a response.
314

315
```python { .api }
316
def input_items.list(
317
    self,
318
    response_id: str,
319
    *,
320
    after: str | None = omit,
321
    include: list[str] | None = omit,
322
    limit: int | None = omit,
323
    order: Literal["asc", "desc"] | None = omit,
324
    extra_headers: dict[str, str] | None = None,
325
    extra_query: dict[str, object] | None = None,
326
    extra_body: dict[str, object] | None = None,
327
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
328
) -> SyncCursorPage[ResponseItem]:
329
    """
330
    Returns a list of input items for a given response.
331

332
    Args:
333
        response_id: The ID of the response.
334
        after: An item ID to list items after, used in pagination.
335
        include: Additional fields to include in the response.
336
        limit: Limit on number of objects (1-100, default 20).
337
        order: Order to return items ('asc' or 'desc', default 'desc').
338

339
    Returns:
340
        Paginated list of response input items.
341
    """
342
```
343

344
### Input Tokens
345

346
Count input tokens for a potential response.
347

348
```python { .api }
349
def input_tokens.count(
350
    self,
351
    *,
352
    conversation: dict | None = omit,
353
    input: str | list[dict] | None = omit,
354
    instructions: str | None = omit,
355
    model: str | None = omit,
356
    parallel_tool_calls: bool | None = omit,
357
    previous_response_id: str | None = omit,
358
    reasoning: dict | None = omit,
359
    text: dict | None = omit,
360
    tool_choice: dict | None = omit,
361
    tools: list[dict] | None = omit,
362
    truncation: Literal["auto", "disabled"] | None = omit,
363
    extra_headers: dict[str, str] | None = None,
364
    extra_query: dict[str, object] | None = None,
365
    extra_body: dict[str, object] | None = None,
366
    timeout: float | httpx.Timeout | None | NotGiven = NOT_GIVEN,
367
) -> InputTokenCountResponse:
368
    """
369
    Get input token counts for a potential response without making the request.
370

371
    Args:
372
        conversation: The conversation context.
373
        input: Text, image, or file inputs.
374
        instructions: System instructions.
375
        model: Model ID.
376
        tools: Available tools.
377

378
    Returns:
379
        InputTokenCountResponse: Token count information.
380
    """
381
```
382

383
## Types
384

385
```python { .api }
386
from typing import Literal
387
from pydantic import BaseModel
388

389
class Response(BaseModel):
390
    """Response object."""
391
    id: str
392
    created_at: int
393
    model: str
394
    object: Literal["response"]
395
    output: list[ResponseContent]
396
    status: Literal["in_progress", "completed", "failed", "cancelled"]
397
    tool_calls: list[ToolCall] | None
398
    usage: Usage | None
399

400
class ResponseContent(BaseModel):
401
    """Response content."""
402
    role: Literal["assistant"]
403
    content: str
404
    type: Literal["text"]
405

406
class ToolCall(BaseModel):
407
    """Tool invocation."""
408
    id: str
409
    type: str
410
    function: dict | None
411
    computer_use: dict | None
412
    apply_patch: dict | None
413

414
class Usage(BaseModel):
415
    """Token usage."""
416
    input_tokens: int
417
    output_tokens: int
418
    total_tokens: int
419
```
420

421
## Tool Types
422

423
### Computer Use
424

425
```python
426
{
427
    "type": "computer_use",
428
    "display_width_px": 1920,
429
    "display_height_px": 1080,
430
    "display_number": 1  # Optional, for multi-monitor
431
}
432
```
433

434
Enables the model to interact with a computer:
435
- View screenshots
436
- Control mouse (move, click)
437
- Type on keyboard
438
- Execute commands
439

440
### Apply Patch
441

442
```python
443
{
444
    "type": "apply_patch"
445
}
446
```
447

448
Enables code modification:
449
- Generate code patches
450
- Apply changes to files
451
- Fix bugs
452
- Refactor code
453

454
### File Search
455

456
```python
457
{
458
    "type": "file_search"
459
}
460
```
461

462
Search uploaded files and documents.
463

464
## Best Practices
465

466
```python
467
from openai import OpenAI
468

469
client = OpenAI()
470

471
# 1. Use for complex multi-step tasks
472
response = client.responses.create(
473
    model="gpt-4",
474
    input={"role": "user", "content": "Analyze this codebase and fix all bugs."},
475
    tools=[
476
        {"type": "file_search"},
477
        {"type": "apply_patch"}
478
    ]
479
)
480

481
# 2. Handle tool calls
482
if response.tool_calls:
483
    for tool_call in response.tool_calls:
484
        if tool_call.type == "apply_patch":
485
            # Review and apply patch
486
            patch = tool_call.apply_patch
487
            print(f"Patch: {patch}")
488

489
# 3. Store important responses
490
response = client.responses.create(
491
    model="gpt-4",
492
    input={"role": "user", "content": "Important analysis"},
493
    store=True
494
)
495

496
# Retrieve later
497
stored = client.responses.retrieve(response.id)
498
```
499

500
## Async Usage
501

502
```python
503
import asyncio
504
from openai import AsyncOpenAI
505

506
async def create_response():
507
    client = AsyncOpenAI()
508

509
    response = await client.responses.create(
510
        model="gpt-4",
511
        input={"role": "user", "content": "Hello!"}
512
    )
513

514
    return response.output[0].content
515

516
content = asyncio.run(create_response())
517
```
518