resources/evals/subresources/runs/methods/retrieve/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1## Get an eval run

2 

3**get** `/evals/{eval_id}/runs/{run_id}`

4 

5Get an evaluation run by ID.

6 

7### Path Parameters

8 

9- `eval_id: string`

10 

11- `run_id: string`

12 

13### Returns

14 

15- `id: string`

16 

17 Unique identifier for the evaluation run.

18 

19- `created_at: number`

20 

21 Unix timestamp (in seconds) when the evaluation run was created.

22 

23- `data_source: CreateEvalJSONLRunDataSource or CreateEvalCompletionsRunDataSource or object { source, type, input_messages, 2 more }`

24 

25 Information about the run's data source.

26 

27 - `CreateEvalJSONLRunDataSource object { source, type }`

28 

29 A JsonlRunDataSource object with that specifies a JSONL file that matches the eval

30 

31 - `source: object { content, type } or object { id, type }`

32 

33 Determines what populates the `item` namespace in the data source.

34 

35 - `EvalJSONLFileContentSource object { content, type }`

36 

37 - `content: array of object { item, sample }`

38 

39 The content of the jsonl file.

40 

41 - `item: map[unknown]`

42 

43 - `sample: optional map[unknown]`

44 

45 - `type: "file_content"`

46 

47 The type of jsonl source. Always `file_content`.

48 

49 - `"file_content"`

50 

51 - `EvalJSONLFileIDSource object { id, type }`

52 

53 - `id: string`

54 

55 The identifier of the file.

56 

57 - `type: "file_id"`

58 

59 The type of jsonl source. Always `file_id`.

60 

61 - `"file_id"`

62 

63 - `type: "jsonl"`

64 

65 The type of data source. Always `jsonl`.

66 

67 - `"jsonl"`

68 

69 - `CreateEvalCompletionsRunDataSource object { source, type, input_messages, 2 more }`

70 

71 A CompletionsRunDataSource object describing a model sampling configuration.

72 

73 - `source: object { content, type } or object { id, type } or object { type, created_after, created_before, 3 more }`

74 

75 Determines what populates the `item` namespace in this run's data source.

76 

77 - `EvalJSONLFileContentSource object { content, type }`

78 

79 - `content: array of object { item, sample }`

80 

81 The content of the jsonl file.

82 

83 - `item: map[unknown]`

84 

85 - `sample: optional map[unknown]`

86 

87 - `type: "file_content"`

88 

89 The type of jsonl source. Always `file_content`.

90 

91 - `"file_content"`

92 

93 - `EvalJSONLFileIDSource object { id, type }`

94 

95 - `id: string`

96 

97 The identifier of the file.

98 

99 - `type: "file_id"`

100 

101 The type of jsonl source. Always `file_id`.

102 

103 - `"file_id"`

104 

105 - `StoredCompletionsRunDataSource object { type, created_after, created_before, 3 more }`

106 

107 A StoredCompletionsRunDataSource configuration describing a set of filters

108 

109 - `type: "stored_completions"`

110 

111 The type of source. Always `stored_completions`.

112 

113 - `"stored_completions"`

114 

115 - `created_after: optional number`

116 

117 An optional Unix timestamp to filter items created after this time.

118 

119 - `created_before: optional number`

120 

121 An optional Unix timestamp to filter items created before this time.

122 

123 - `limit: optional number`

124 

125 An optional maximum number of items to return.

126 

127 - `metadata: optional Metadata`

128 

129 Set of 16 key-value pairs that can be attached to an object. This can be

130 useful for storing additional information about the object in a structured

131 format, and querying for objects via API or the dashboard.

132 

133 Keys are strings with a maximum length of 64 characters. Values are strings

134 with a maximum length of 512 characters.

135 

136 - `model: optional string`

137 

138 An optional model to filter by (e.g., 'gpt-4o').

139 

140 - `type: "completions"`

141 

142 The type of run data source. Always `completions`.

143 

144 - `"completions"`

145 

146 - `input_messages: optional object { template, type } or object { item_reference, type }`

147 

148 Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace.

149 

150 - `TemplateInputMessages object { template, type }`

151 

152 - `template: array of EasyInputMessage or object { content, role, type }`

153 

154 A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}.

155 

156 - `EasyInputMessage object { content, role, phase, type }`

157 

158 A message input to the model with a role indicating instruction following

159 hierarchy. Instructions given with the `developer` or `system` role take

160 precedence over instructions given with the `user` role. Messages with the

161 `assistant` role are presumed to have been generated by the model in previous

162 interactions.

163 

164 - `content: string or ResponseInputMessageContentList`

165 

166 Text, image, or audio input to the model, used to generate a response.

167 Can also contain previous assistant responses.

168 

169 - `TextInput = string`

170 

171 A text input to the model.

172 

173 - `ResponseInputMessageContentList = array of ResponseInputContent`

174 

175 A list of one or many input items to the model, containing different content

176 types.

177 

178 - `ResponseInputText object { text, type }`

179 

180 A text input to the model.

181 

182 - `text: string`

183 

184 The text input to the model.

185 

186 - `type: "input_text"`

187 

188 The type of the input item. Always `input_text`.

189 

190 - `"input_text"`

191 

192 - `ResponseInputImage object { detail, type, file_id, image_url }`

193 

194 An image input to the model. Learn about [image inputs](/docs/guides/vision).

195 

196 - `detail: "low" or "high" or "auto" or "original"`

197 

198 The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`.

199 

200 - `"low"`

201 

202 - `"high"`

203 

204 - `"auto"`

205 

206 - `"original"`

207 

208 - `type: "input_image"`

209 

210 The type of the input item. Always `input_image`.

211 

212 - `"input_image"`

213 

214 - `file_id: optional string`

215 

216 The ID of the file to be sent to the model.

217 

218 - `image_url: optional string`

219 

220 The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL.

221 

222 - `ResponseInputFile object { type, detail, file_data, 3 more }`

223 

224 A file input to the model.

225 

226 - `type: "input_file"`

227 

228 The type of the input item. Always `input_file`.

229 

230 - `"input_file"`

231 

232 - `detail: optional "low" or "high"`

233 

234 The detail level of the file to be sent to the model. Use `low` for the default rendering behavior, or `high` to render the file at higher quality. Defaults to `low`.

235 

236 - `"low"`

237 

238 - `"high"`

239 

240 - `file_data: optional string`

241 

242 The content of the file to be sent to the model.

243 

244 - `file_id: optional string`

245 

246 The ID of the file to be sent to the model.

247 

248 - `file_url: optional string`

249 

250 The URL of the file to be sent to the model.

251 

252 - `filename: optional string`

253 

254 The name of the file to be sent to the model.

255 

256 - `role: "user" or "assistant" or "system" or "developer"`

257 

258 The role of the message input. One of `user`, `assistant`, `system`, or

259 `developer`.

260 

261 - `"user"`

262 

263 - `"assistant"`

264 

265 - `"system"`

266 

267 - `"developer"`

268 

269 - `phase: optional "commentary" or "final_answer"`

270 

271 Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`).

272 For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend

273 phase on all assistant messages — dropping it can degrade performance. Not used for user messages.

274 

275 - `"commentary"`

276 

277 - `"final_answer"`

278 

279 - `type: optional "message"`

280 

281 The type of the message input. Always `message`.

282 

283 - `"message"`

284 

285 - `EvalMessageObject object { content, role, type }`

286 

287 A message input to the model with a role indicating instruction following

288 hierarchy. Instructions given with the `developer` or `system` role take

289 precedence over instructions given with the `user` role. Messages with the

290 `assistant` role are presumed to have been generated by the model in previous

291 interactions.

292 

293 - `content: string or ResponseInputText or object { text, type } or 3 more`

294 

295 Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items.

296 

297 - `TextInput = string`

298 

299 A text input to the model.

300 

301 - `ResponseInputText object { text, type }`

302 

303 A text input to the model.

304 

305 - `OutputText object { text, type }`

306 

307 A text output from the model.

308 

309 - `text: string`

310 

311 The text output from the model.

312 

313 - `type: "output_text"`

314 

315 The type of the output text. Always `output_text`.

316 

317 - `"output_text"`

318 

319 - `InputImage object { image_url, type, detail }`

320 

321 An image input block used within EvalItem content arrays.

322 

323 - `image_url: string`

324 

325 The URL of the image input.

326 

327 - `type: "input_image"`

328 

329 The type of the image input. Always `input_image`.

330 

331 - `"input_image"`

332 

333 - `detail: optional string`

334 

335 The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.

336 

337 - `ResponseInputAudio object { input_audio, type }`

338 

339 An audio input to the model.

340 

341 - `input_audio: object { data, format }`

342 

343 - `data: string`

344 

345 Base64-encoded audio data.

346 

347 - `format: "mp3" or "wav"`

348 

349 The format of the audio data. Currently supported formats are `mp3` and

350 `wav`.

351 

352 - `"mp3"`

353 

354 - `"wav"`

355 

356 - `type: "input_audio"`

357 

358 The type of the input item. Always `input_audio`.

359 

360 - `"input_audio"`

361 

362 - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more`

363 

364 A list of inputs, each of which may be either an input text, output text, input

365 image, or input audio object.

366 

367 - `TextInput = string`

368 

369 A text input to the model.

370 

371 - `ResponseInputText object { text, type }`

372 

373 A text input to the model.

374 

375 - `OutputText object { text, type }`

376 

377 A text output from the model.

378 

379 - `text: string`

380 

381 The text output from the model.

382 

383 - `type: "output_text"`

384 

385 The type of the output text. Always `output_text`.

386 

387 - `"output_text"`

388 

389 - `InputImage object { image_url, type, detail }`

390 

391 An image input block used within EvalItem content arrays.

392 

393 - `image_url: string`

394 

395 The URL of the image input.

396 

397 - `type: "input_image"`

398 

399 The type of the image input. Always `input_image`.

400 

401 - `"input_image"`

402 

403 - `detail: optional string`

404 

405 The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.

406 

407 - `ResponseInputAudio object { input_audio, type }`

408 

409 An audio input to the model.

410 

411 - `role: "user" or "assistant" or "system" or "developer"`

412 

413 The role of the message input. One of `user`, `assistant`, `system`, or

414 `developer`.

415 

416 - `"user"`

417 

418 - `"assistant"`

419 

420 - `"system"`

421 

422 - `"developer"`

423 

424 - `type: optional "message"`

425 

426 The type of the message input. Always `message`.

427 

428 - `"message"`

429 

430 - `type: "template"`

431 

432 The type of input messages. Always `template`.

433 

434 - `"template"`

435 

436 - `ItemReferenceInputMessages object { item_reference, type }`

437 

438 - `item_reference: string`

439 

440 A reference to a variable in the `item` namespace. Ie, "item.input_trajectory"

441 

442 - `type: "item_reference"`

443 

444 The type of input messages. Always `item_reference`.

445 

446 - `"item_reference"`

447 

448 - `model: optional string`

449 

450 The name of the model to use for generating completions (e.g. "o3-mini").

451 

452 - `sampling_params: optional object { max_completion_tokens, reasoning_effort, response_format, 4 more }`

453 

454 - `max_completion_tokens: optional number`

455 

456 The maximum number of tokens in the generated output.

457 

458 - `reasoning_effort: optional ReasoningEffort`

459 

460 Constrains effort on reasoning for

461 [reasoning models](https://platform.openai.com/docs/guides/reasoning).

462 Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing

463 reasoning effort can result in faster responses and fewer tokens used

464 on reasoning in a response.

465 

466 - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1.

467 - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`.

468 - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort.

469 - `xhigh` is supported for all models after `gpt-5.1-codex-max`.

470 

471 - `"none"`

472 

473 - `"minimal"`

474 

475 - `"low"`

476 

477 - `"medium"`

478 

479 - `"high"`

480 

481 - `"xhigh"`

482 

483 - `response_format: optional ResponseFormatText or ResponseFormatJSONSchema or ResponseFormatJSONObject`

484 

485 An object specifying the format that the model must output.

486 

487 Setting to `{ "type": "json_schema", "json_schema": {...} }` enables

488 Structured Outputs which ensures the model will match your supplied JSON

489 schema. Learn more in the [Structured Outputs

490 guide](/docs/guides/structured-outputs).

491 

492 Setting to `{ "type": "json_object" }` enables the older JSON mode, which

493 ensures the message the model generates is valid JSON. Using `json_schema`

494 is preferred for models that support it.

495 

496 - `ResponseFormatText object { type }`

497 

498 Default response format. Used to generate text responses.

499 

500 - `type: "text"`

501 

502 The type of response format being defined. Always `text`.

503 

504 - `"text"`

505 

506 - `ResponseFormatJSONSchema object { json_schema, type }`

507 

508 JSON Schema response format. Used to generate structured JSON responses.

509 Learn more about [Structured Outputs](/docs/guides/structured-outputs).

510 

511 - `json_schema: object { name, description, schema, strict }`

512 

513 Structured Outputs configuration options, including a JSON Schema.

514 

515 - `name: string`

516 

517 The name of the response format. Must be a-z, A-Z, 0-9, or contain

518 underscores and dashes, with a maximum length of 64.

519 

520 - `description: optional string`

521 

522 A description of what the response format is for, used by the model to

523 determine how to respond in the format.

524 

525 - `schema: optional map[unknown]`

526 

527 The schema for the response format, described as a JSON Schema object.

528 Learn how to build JSON schemas [here](https://json-schema.org/).

529 

530 - `strict: optional boolean`

531 

532 Whether to enable strict schema adherence when generating the output.

533 If set to true, the model will always follow the exact schema defined

534 in the `schema` field. Only a subset of JSON Schema is supported when

535 `strict` is `true`. To learn more, read the [Structured Outputs

536 guide](/docs/guides/structured-outputs).

537 

538 - `type: "json_schema"`

539 

540 The type of response format being defined. Always `json_schema`.

541 

542 - `"json_schema"`

543 

544 - `ResponseFormatJSONObject object { type }`

545 

546 JSON object response format. An older method of generating JSON responses.

547 Using `json_schema` is recommended for models that support it. Note that the

548 model will not generate JSON without a system or user message instructing it

549 to do so.

550 

551 - `type: "json_object"`

552 

553 The type of response format being defined. Always `json_object`.

554 

555 - `"json_object"`

556 

557 - `seed: optional number`

558 

559 A seed value to initialize the randomness, during sampling.

560 

561 - `temperature: optional number`

562 

563 A higher temperature increases randomness in the outputs.

564 

565 - `tools: optional array of ChatCompletionFunctionTool`

566 

567 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.

568 

569 - `function: FunctionDefinition`

570 

571 - `name: string`

572 

573 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.

574 

575 - `description: optional string`

576 

577 A description of what the function does, used by the model to choose when and how to call the function.

578 

579 - `parameters: optional FunctionParameters`

580 

581 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.

582 

583 Omitting `parameters` defines a function with an empty parameter list.

584 

585 - `strict: optional boolean`

586 

587 Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling).

588 

589 - `type: "function"`

590 

591 The type of the tool. Currently, only `function` is supported.

592 

593 - `"function"`

594 

595 - `top_p: optional number`

596 

597 An alternative to temperature for nucleus sampling; 1.0 includes all tokens.

598 

599 - `ResponsesRunDataSource object { source, type, input_messages, 2 more }`

600 

601 A ResponsesRunDataSource object describing a model sampling configuration.

602 

603 - `source: object { content, type } or object { id, type } or object { type, created_after, created_before, 8 more }`

604 

605 Determines what populates the `item` namespace in this run's data source.

606 

607 - `EvalJSONLFileContentSource object { content, type }`

608 

609 - `content: array of object { item, sample }`

610 

611 The content of the jsonl file.

612 

613 - `item: map[unknown]`

614 

615 - `sample: optional map[unknown]`

616 

617 - `type: "file_content"`

618 

619 The type of jsonl source. Always `file_content`.

620 

621 - `"file_content"`

622 

623 - `EvalJSONLFileIDSource object { id, type }`

624 

625 - `id: string`

626 

627 The identifier of the file.

628 

629 - `type: "file_id"`

630 

631 The type of jsonl source. Always `file_id`.

632 

633 - `"file_id"`

634 

635 - `EvalResponsesSource object { type, created_after, created_before, 8 more }`

636 

637 A EvalResponsesSource object describing a run data source configuration.

638 

639 - `type: "responses"`

640 

641 The type of run data source. Always `responses`.

642 

643 - `"responses"`

644 

645 - `created_after: optional number`

646 

647 Only include items created after this timestamp (inclusive). This is a query parameter used to select responses.

648 

649 - `created_before: optional number`

650 

651 Only include items created before this timestamp (inclusive). This is a query parameter used to select responses.

652 

653 - `instructions_search: optional string`

654 

655 Optional string to search the 'instructions' field. This is a query parameter used to select responses.

656 

657 - `metadata: optional unknown`

658 

659 Metadata filter for the responses. This is a query parameter used to select responses.

660 

661 - `model: optional string`

662 

663 The name of the model to find responses for. This is a query parameter used to select responses.

664 

665 - `reasoning_effort: optional ReasoningEffort`

666 

667 Constrains effort on reasoning for

668 [reasoning models](https://platform.openai.com/docs/guides/reasoning).

669 Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing

670 reasoning effort can result in faster responses and fewer tokens used

671 on reasoning in a response.

672 

673 - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1.

674 - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`.

675 - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort.

676 - `xhigh` is supported for all models after `gpt-5.1-codex-max`.

677 

678 - `temperature: optional number`

679 

680 Sampling temperature. This is a query parameter used to select responses.

681 

682 - `tools: optional array of string`

683 

684 List of tool names. This is a query parameter used to select responses.

685 

686 - `top_p: optional number`

687 

688 Nucleus sampling parameter. This is a query parameter used to select responses.

689 

690 - `users: optional array of string`

691 

692 List of user identifiers. This is a query parameter used to select responses.

693 

694 - `type: "responses"`

695 

696 The type of run data source. Always `responses`.

697 

698 - `"responses"`

699 

700 - `input_messages: optional object { template, type } or object { item_reference, type }`

701 

702 Used when sampling from a model. Dictates the structure of the messages passed into the model. Can either be a reference to a prebuilt trajectory (ie, `item.input_trajectory`), or a template with variable references to the `item` namespace.

703 

704 - `InputMessagesTemplate object { template, type }`

705 

706 - `template: array of object { content, role } or object { content, role, type }`

707 

708 A list of chat messages forming the prompt or context. May include variable references to the `item` namespace, ie {{item.name}}.

709 

710 - `ChatMessage object { content, role }`

711 

712 - `content: string`

713 

714 The content of the message.

715 

716 - `role: string`

717 

718 The role of the message (e.g. "system", "assistant", "user").

719 

720 - `EvalMessageObject object { content, role, type }`

721 

722 A message input to the model with a role indicating instruction following

723 hierarchy. Instructions given with the `developer` or `system` role take

724 precedence over instructions given with the `user` role. Messages with the

725 `assistant` role are presumed to have been generated by the model in previous

726 interactions.

727 

728 - `content: string or ResponseInputText or object { text, type } or 3 more`

729 

730 Inputs to the model - can contain template strings. Supports text, output text, input images, and input audio, either as a single item or an array of items.

731 

732 - `TextInput = string`

733 

734 A text input to the model.

735 

736 - `ResponseInputText object { text, type }`

737 

738 A text input to the model.

739 

740 - `OutputText object { text, type }`

741 

742 A text output from the model.

743 

744 - `text: string`

745 

746 The text output from the model.

747 

748 - `type: "output_text"`

749 

750 The type of the output text. Always `output_text`.

751 

752 - `"output_text"`

753 

754 - `InputImage object { image_url, type, detail }`

755 

756 An image input block used within EvalItem content arrays.

757 

758 - `image_url: string`

759 

760 The URL of the image input.

761 

762 - `type: "input_image"`

763 

764 The type of the image input. Always `input_image`.

765 

766 - `"input_image"`

767 

768 - `detail: optional string`

769 

770 The detail level of the image to be sent to the model. One of `high`, `low`, or `auto`. Defaults to `auto`.

771 

772 - `ResponseInputAudio object { input_audio, type }`

773 

774 An audio input to the model.

775 

776 - `GraderInputs = array of string or ResponseInputText or object { text, type } or 2 more`

777 

778 A list of inputs, each of which may be either an input text, output text, input

779 image, or input audio object.

780 

781 - `role: "user" or "assistant" or "system" or "developer"`

782 

783 The role of the message input. One of `user`, `assistant`, `system`, or

784 `developer`.

785 

786 - `"user"`

787 

788 - `"assistant"`

789 

790 - `"system"`

791 

792 - `"developer"`

793 

794 - `type: optional "message"`

795 

796 The type of the message input. Always `message`.

797 

798 - `"message"`

799 

800 - `type: "template"`

801 

802 The type of input messages. Always `template`.

803 

804 - `"template"`

805 

806 - `InputMessagesItemReference object { item_reference, type }`

807 

808 - `item_reference: string`

809 

810 A reference to a variable in the `item` namespace. Ie, "item.name"

811 

812 - `type: "item_reference"`

813 

814 The type of input messages. Always `item_reference`.

815 

816 - `"item_reference"`

817 

818 - `model: optional string`

819 

820 The name of the model to use for generating completions (e.g. "o3-mini").

821 

822 - `sampling_params: optional object { max_completion_tokens, reasoning_effort, seed, 4 more }`

823 

824 - `max_completion_tokens: optional number`

825 

826 The maximum number of tokens in the generated output.

827 

828 - `reasoning_effort: optional ReasoningEffort`

829 

830 Constrains effort on reasoning for

831 [reasoning models](https://platform.openai.com/docs/guides/reasoning).

832 Currently supported values are `none`, `minimal`, `low`, `medium`, `high`, and `xhigh`. Reducing

833 reasoning effort can result in faster responses and fewer tokens used

834 on reasoning in a response.

835 

836 - `gpt-5.1` defaults to `none`, which does not perform reasoning. The supported reasoning values for `gpt-5.1` are `none`, `low`, `medium`, and `high`. Tool calls are supported for all reasoning values in gpt-5.1.

837 - All models before `gpt-5.1` default to `medium` reasoning effort, and do not support `none`.

838 - The `gpt-5-pro` model defaults to (and only supports) `high` reasoning effort.

839 - `xhigh` is supported for all models after `gpt-5.1-codex-max`.

840 

841 - `seed: optional number`

842 

843 A seed value to initialize the randomness, during sampling.

844 

845 - `temperature: optional number`

846 

847 A higher temperature increases randomness in the outputs.

848 

849 - `text: optional object { format }`

850 

851 Configuration options for a text response from the model. Can be plain

852 text or structured JSON data. Learn more:

853 

854 - [Text inputs and outputs](/docs/guides/text)

855 - [Structured Outputs](/docs/guides/structured-outputs)

856 

857 - `format: optional ResponseFormatTextConfig`

858 

859 An object specifying the format that the model must output.

860 

861 Configuring `{ "type": "json_schema" }` enables Structured Outputs,

862 which ensures the model will match your supplied JSON schema. Learn more in the

863 [Structured Outputs guide](/docs/guides/structured-outputs).

864 

865 The default format is `{ "type": "text" }` with no additional options.

866 

867 **Not recommended for gpt-4o and newer models:**

868 

869 Setting to `{ "type": "json_object" }` enables the older JSON mode, which

870 ensures the message the model generates is valid JSON. Using `json_schema`

871 is preferred for models that support it.

872 

873 - `ResponseFormatText object { type }`

874 

875 Default response format. Used to generate text responses.

876 

877 - `ResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }`

878 

879 JSON Schema response format. Used to generate structured JSON responses.

880 Learn more about [Structured Outputs](/docs/guides/structured-outputs).

881 

882 - `name: string`

883 

884 The name of the response format. Must be a-z, A-Z, 0-9, or contain

885 underscores and dashes, with a maximum length of 64.

886 

887 - `schema: map[unknown]`

888 

889 The schema for the response format, described as a JSON Schema object.

890 Learn how to build JSON schemas [here](https://json-schema.org/).

891 

892 - `type: "json_schema"`

893 

894 The type of response format being defined. Always `json_schema`.

895 

896 - `"json_schema"`

897 

898 - `description: optional string`

899 

900 A description of what the response format is for, used by the model to

901 determine how to respond in the format.

902 

903 - `strict: optional boolean`

904 

905 Whether to enable strict schema adherence when generating the output.

906 If set to true, the model will always follow the exact schema defined

907 in the `schema` field. Only a subset of JSON Schema is supported when

908 `strict` is `true`. To learn more, read the [Structured Outputs

909 guide](/docs/guides/structured-outputs).

910 

911 - `ResponseFormatJSONObject object { type }`

912 

913 JSON object response format. An older method of generating JSON responses.

914 Using `json_schema` is recommended for models that support it. Note that the

915 model will not generate JSON without a system or user message instructing it

916 to do so.

917 

918 - `tools: optional array of object { name, parameters, strict, 3 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 12 more`

919 

920 An array of tools the model may call while generating a response. You

921 can specify which tool to use by setting the `tool_choice` parameter.

922 

923 The two categories of tools you can provide the model are:

924 

925 - **Built-in tools**: Tools that are provided by OpenAI that extend the

926 model's capabilities, like [web search](/docs/guides/tools-web-search)

927 or [file search](/docs/guides/tools-file-search). Learn more about

928 [built-in tools](/docs/guides/tools).

929 - **Function calls (custom tools)**: Functions that are defined by you,

930 enabling the model to call your own code. Learn more about

931 [function calling](/docs/guides/function-calling).

932 

933 - `Function object { name, parameters, strict, 3 more }`

934 

935 Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling).

936 

937 - `name: string`

938 

939 The name of the function to call.

940 

941 - `parameters: map[unknown]`

942 

943 A JSON schema object describing the parameters of the function.

944 

945 - `strict: boolean`

946 

947 Whether to enforce strict parameter validation. Default `true`.

948 

949 - `type: "function"`

950 

951 The type of the function tool. Always `function`.

952 

953 - `"function"`

954 

955 - `defer_loading: optional boolean`

956 

957 Whether this function is deferred and loaded via tool search.

958 

959 - `description: optional string`

960 

961 A description of the function. Used by the model to determine whether or not to call the function.

962 

963 - `FileSearch object { type, vector_store_ids, filters, 2 more }`

964 

965 A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search).

966 

967 - `type: "file_search"`

968 

969 The type of the file search tool. Always `file_search`.

970 

971 - `"file_search"`

972 

973 - `vector_store_ids: array of string`

974 

975 The IDs of the vector stores to search.

976 

977 - `filters: optional ComparisonFilter or CompoundFilter`

978 

979 A filter to apply.

980 

981 - `ComparisonFilter object { key, type, value }`

982 

983 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

984 

985 - `key: string`

986 

987 The key to compare against the value.

988 

989 - `type: "eq" or "ne" or "gt" or 5 more`

990 

991 Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`.

992 

993 - `eq`: equals

994 - `ne`: not equal

995 - `gt`: greater than

996 - `gte`: greater than or equal

997 - `lt`: less than

998 - `lte`: less than or equal

999 - `in`: in

1000 - `nin`: not in

1001 

1002 - `"eq"`

1003 

1004 - `"ne"`

1005 

1006 - `"gt"`

1007 

1008 - `"gte"`

1009 

1010 - `"lt"`

1011 

1012 - `"lte"`

1013 

1014 - `"in"`

1015 

1016 - `"nin"`

1017 

1018 - `value: string or number or boolean or array of string or number`

1019 

1020 The value to compare against the attribute key; supports string, number, or boolean types.

1021 

1022 - `string`

1023 

1024 - `number`

1025 

1026 - `boolean`

1027 

1028 - `array of string or number`

1029 

1030 - `string`

1031 

1032 - `number`

1033 

1034 - `CompoundFilter object { filters, type }`

1035 

1036 Combine multiple filters using `and` or `or`.

1037 

1038 - `filters: array of ComparisonFilter or unknown`

1039 

1040 Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`.

1041 

1042 - `ComparisonFilter object { key, type, value }`

1043 

1044 A filter used to compare a specified attribute key to a given value using a defined comparison operation.

1045 

1046 - `unknown`

1047 

1048 - `type: "and" or "or"`

1049 

1050 Type of operation: `and` or `or`.

1051 

1052 - `"and"`

1053 

1054 - `"or"`

1055 

1056 - `max_num_results: optional number`

1057 

1058 The maximum number of results to return. This number should be between 1 and 50 inclusive.

1059 

1060 - `ranking_options: optional object { hybrid_search, ranker, score_threshold }`

1061 

1062 Ranking options for search.

1063 

1064 - `hybrid_search: optional object { embedding_weight, text_weight }`

1065 

1066 Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled.

1067 

1068 - `embedding_weight: number`

1069 

1070 The weight of the embedding in the reciprocal ranking fusion.

1071 

1072 - `text_weight: number`

1073 

1074 The weight of the text in the reciprocal ranking fusion.

1075 

1076 - `ranker: optional "auto" or "default-2024-11-15"`

1077 

1078 The ranker to use for the file search.

1079 

1080 - `"auto"`

1081 

1082 - `"default-2024-11-15"`

1083 

1084 - `score_threshold: optional number`

1085 

1086 The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results.

1087 

1088 - `Computer object { type }`

1089 

1090 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1091 

1092 - `type: "computer"`

1093 

1094 The type of the computer tool. Always `computer`.

1095 

1096 - `"computer"`

1097 

1098 - `ComputerUsePreview object { display_height, display_width, environment, type }`

1099 

1100 A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use).

1101 

1102 - `display_height: number`

1103 

1104 The height of the computer display.

1105 

1106 - `display_width: number`

1107 

1108 The width of the computer display.

1109 

1110 - `environment: "windows" or "mac" or "linux" or 2 more`

1111 

1112 The type of computer environment to control.

1113 

1114 - `"windows"`

1115 

1116 - `"mac"`

1117 

1118 - `"linux"`

1119 

1120 - `"ubuntu"`

1121 

1122 - `"browser"`

1123 

1124 - `type: "computer_use_preview"`

1125 

1126 The type of the computer use tool. Always `computer_use_preview`.

1127 

1128 - `"computer_use_preview"`

1129 

1130 - `WebSearch object { type, filters, search_context_size, user_location }`

1131 

1132 Search the Internet for sources related to the prompt. Learn more about the

1133 [web search tool](/docs/guides/tools-web-search).

1134 

1135 - `type: "web_search" or "web_search_2025_08_26"`

1136 

1137 The type of the web search tool. One of `web_search` or `web_search_2025_08_26`.

1138 

1139 - `"web_search"`

1140 

1141 - `"web_search_2025_08_26"`

1142 

1143 - `filters: optional object { allowed_domains }`

1144 

1145 Filters for the search.

1146 

1147 - `allowed_domains: optional array of string`

1148 

1149 Allowed domains for the search. If not provided, all domains are allowed.

1150 Subdomains of the provided domains are allowed as well.

1151 

1152 Example: `["pubmed.ncbi.nlm.nih.gov"]`

1153 

1154 - `search_context_size: optional "low" or "medium" or "high"`

1155 

1156 High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.

1157 

1158 - `"low"`

1159 

1160 - `"medium"`

1161 

1162 - `"high"`

1163 

1164 - `user_location: optional object { city, country, region, 2 more }`

1165 

1166 The approximate location of the user.

1167 

1168 - `city: optional string`

1169 

1170 Free text input for the city of the user, e.g. `San Francisco`.

1171 

1172 - `country: optional string`

1173 

1174 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

1175 

1176 - `region: optional string`

1177 

1178 Free text input for the region of the user, e.g. `California`.

1179 

1180 - `timezone: optional string`

1181 

1182 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

1183 

1184 - `type: optional "approximate"`

1185 

1186 The type of location approximation. Always `approximate`.

1187 

1188 - `"approximate"`

1189 

1190 - `Mcp object { server_label, type, allowed_tools, 7 more }`

1191 

1192 Give the model access to additional tools via remote Model Context Protocol

1193 (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp).

1194 

1195 - `server_label: string`

1196 

1197 A label for this MCP server, used to identify it in tool calls.

1198 

1199 - `type: "mcp"`

1200 

1201 The type of the MCP tool. Always `mcp`.

1202 

1203 - `"mcp"`

1204 

1205 - `allowed_tools: optional array of string or object { read_only, tool_names }`

1206 

1207 List of allowed tool names or a filter object.

1208 

1209 - `McpAllowedTools = array of string`

1210 

1211 A string array of allowed tool names

1212 

1213 - `McpToolFilter object { read_only, tool_names }`

1214 

1215 A filter object to specify which tools are allowed.

1216 

1217 - `read_only: optional boolean`

1218 

1219 Indicates whether or not a tool modifies data or is read-only. If an

1220 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1221 it will match this filter.

1222 

1223 - `tool_names: optional array of string`

1224 

1225 List of allowed tool names.

1226 

1227 - `authorization: optional string`

1228 

1229 An OAuth access token that can be used with a remote MCP server, either

1230 with a custom MCP server URL or a service connector. Your application

1231 must handle the OAuth authorization flow and provide the token here.

1232 

1233 - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more`

1234 

1235 Identifier for service connectors, like those available in ChatGPT. One of

1236 `server_url` or `connector_id` must be provided. Learn more about service

1237 connectors [here](/docs/guides/tools-remote-mcp#connectors).

1238 

1239 Currently supported `connector_id` values are:

1240 

1241 - Dropbox: `connector_dropbox`

1242 - Gmail: `connector_gmail`

1243 - Google Calendar: `connector_googlecalendar`

1244 - Google Drive: `connector_googledrive`

1245 - Microsoft Teams: `connector_microsoftteams`

1246 - Outlook Calendar: `connector_outlookcalendar`

1247 - Outlook Email: `connector_outlookemail`

1248 - SharePoint: `connector_sharepoint`

1249 

1250 - `"connector_dropbox"`

1251 

1252 - `"connector_gmail"`

1253 

1254 - `"connector_googlecalendar"`

1255 

1256 - `"connector_googledrive"`

1257 

1258 - `"connector_microsoftteams"`

1259 

1260 - `"connector_outlookcalendar"`

1261 

1262 - `"connector_outlookemail"`

1263 

1264 - `"connector_sharepoint"`

1265 

1266 - `defer_loading: optional boolean`

1267 

1268 Whether this MCP tool is deferred and discovered via tool search.

1269 

1270 - `headers: optional map[string]`

1271 

1272 Optional HTTP headers to send to the MCP server. Use for authentication

1273 or other purposes.

1274 

1275 - `require_approval: optional object { always, never } or "always" or "never"`

1276 

1277 Specify which of the MCP server's tools require approval.

1278 

1279 - `McpToolApprovalFilter object { always, never }`

1280 

1281 Specify which of the MCP server's tools require approval. Can be

1282 `always`, `never`, or a filter object associated with tools

1283 that require approval.

1284 

1285 - `always: optional object { read_only, tool_names }`

1286 

1287 A filter object to specify which tools are allowed.

1288 

1289 - `read_only: optional boolean`

1290 

1291 Indicates whether or not a tool modifies data or is read-only. If an

1292 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1293 it will match this filter.

1294 

1295 - `tool_names: optional array of string`

1296 

1297 List of allowed tool names.

1298 

1299 - `never: optional object { read_only, tool_names }`

1300 

1301 A filter object to specify which tools are allowed.

1302 

1303 - `read_only: optional boolean`

1304 

1305 Indicates whether or not a tool modifies data or is read-only. If an

1306 MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint),

1307 it will match this filter.

1308 

1309 - `tool_names: optional array of string`

1310 

1311 List of allowed tool names.

1312 

1313 - `McpToolApprovalSetting = "always" or "never"`

1314 

1315 Specify a single approval policy for all tools. One of `always` or

1316 `never`. When set to `always`, all tools will require approval. When

1317 set to `never`, all tools will not require approval.

1318 

1319 - `"always"`

1320 

1321 - `"never"`

1322 

1323 - `server_description: optional string`

1324 

1325 Optional description of the MCP server, used to provide more context.

1326 

1327 - `server_url: optional string`

1328 

1329 The URL for the MCP server. One of `server_url` or `connector_id` must be

1330 provided.

1331 

1332 - `CodeInterpreter object { container, type }`

1333 

1334 A tool that runs Python code to help generate a response to a prompt.

1335 

1336 - `container: string or object { type, file_ids, memory_limit, network_policy }`

1337 

1338 The code interpreter container. Can be a container ID or an object that

1339 specifies uploaded file IDs to make available to your code, along with an

1340 optional `memory_limit` setting.

1341 

1342 - `string`

1343 

1344 The container ID.

1345 

1346 - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }`

1347 

1348 Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on.

1349 

1350 - `type: "auto"`

1351 

1352 Always `auto`.

1353 

1354 - `"auto"`

1355 

1356 - `file_ids: optional array of string`

1357 

1358 An optional list of uploaded files to make available to your code.

1359 

1360 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"`

1361 

1362 The memory limit for the code interpreter container.

1363 

1364 - `"1g"`

1365 

1366 - `"4g"`

1367 

1368 - `"16g"`

1369 

1370 - `"64g"`

1371 

1372 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1373 

1374 Network access policy for the container.

1375 

1376 - `ContainerNetworkPolicyDisabled object { type }`

1377 

1378 - `type: "disabled"`

1379 

1380 Disable outbound network access. Always `disabled`.

1381 

1382 - `"disabled"`

1383 

1384 - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }`

1385 

1386 - `allowed_domains: array of string`

1387 

1388 A list of allowed domains when type is `allowlist`.

1389 

1390 - `type: "allowlist"`

1391 

1392 Allow outbound network access only to specified domains. Always `allowlist`.

1393 

1394 - `"allowlist"`

1395 

1396 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1397 

1398 Optional domain-scoped secrets for allowlisted domains.

1399 

1400 - `domain: string`

1401 

1402 The domain associated with the secret.

1403 

1404 - `name: string`

1405 

1406 The name of the secret to inject for the domain.

1407 

1408 - `value: string`

1409 

1410 The secret value to inject for the domain.

1411 

1412 - `type: "code_interpreter"`

1413 

1414 The type of the code interpreter tool. Always `code_interpreter`.

1415 

1416 - `"code_interpreter"`

1417 

1418 - `ImageGeneration object { type, action, background, 9 more }`

1419 

1420 A tool that generates images using the GPT image models.

1421 

1422 - `type: "image_generation"`

1423 

1424 The type of the image generation tool. Always `image_generation`.

1425 

1426 - `"image_generation"`

1427 

1428 - `action: optional "generate" or "edit" or "auto"`

1429 

1430 Whether to generate a new image or edit an existing image. Default: `auto`.

1431 

1432 - `"generate"`

1433 

1434 - `"edit"`

1435 

1436 - `"auto"`

1437 

1438 - `background: optional "transparent" or "opaque" or "auto"`

1439 

1440 Background type for the generated image. One of `transparent`,

1441 `opaque`, or `auto`. Default: `auto`.

1442 

1443 - `"transparent"`

1444 

1445 - `"opaque"`

1446 

1447 - `"auto"`

1448 

1449 - `input_fidelity: optional "high" or "low"`

1450 

1451 Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.

1452 

1453 - `"high"`

1454 

1455 - `"low"`

1456 

1457 - `input_image_mask: optional object { file_id, image_url }`

1458 

1459 Optional mask for inpainting. Contains `image_url`

1460 (string, optional) and `file_id` (string, optional).

1461 

1462 - `file_id: optional string`

1463 

1464 File ID for the mask image.

1465 

1466 - `image_url: optional string`

1467 

1468 Base64-encoded mask image.

1469 

1470 - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"`

1471 

1472 The image generation model to use. Default: `gpt-image-1`.

1473 

1474 - `string`

1475 

1476 - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"`

1477 

1478 The image generation model to use. Default: `gpt-image-1`.

1479 

1480 - `"gpt-image-1"`

1481 

1482 - `"gpt-image-1-mini"`

1483 

1484 - `"gpt-image-1.5"`

1485 

1486 - `moderation: optional "auto" or "low"`

1487 

1488 Moderation level for the generated image. Default: `auto`.

1489 

1490 - `"auto"`

1491 

1492 - `"low"`

1493 

1494 - `output_compression: optional number`

1495 

1496 Compression level for the output image. Default: 100.

1497 

1498 - `output_format: optional "png" or "webp" or "jpeg"`

1499 

1500 The output format of the generated image. One of `png`, `webp`, or

1501 `jpeg`. Default: `png`.

1502 

1503 - `"png"`

1504 

1505 - `"webp"`

1506 

1507 - `"jpeg"`

1508 

1509 - `partial_images: optional number`

1510 

1511 Number of partial images to generate in streaming mode, from 0 (default value) to 3.

1512 

1513 - `quality: optional "low" or "medium" or "high" or "auto"`

1514 

1515 The quality of the generated image. One of `low`, `medium`, `high`,

1516 or `auto`. Default: `auto`.

1517 

1518 - `"low"`

1519 

1520 - `"medium"`

1521 

1522 - `"high"`

1523 

1524 - `"auto"`

1525 

1526 - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1527 

1528 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1529 

1530 - `string`

1531 

1532 - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"`

1533 

1534 The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`.

1535 

1536 - `"1024x1024"`

1537 

1538 - `"1024x1536"`

1539 

1540 - `"1536x1024"`

1541 

1542 - `"auto"`

1543 

1544 - `LocalShell object { type }`

1545 

1546 A tool that allows the model to execute shell commands in a local environment.

1547 

1548 - `type: "local_shell"`

1549 

1550 The type of the local shell tool. Always `local_shell`.

1551 

1552 - `"local_shell"`

1553 

1554 - `Shell object { type, environment }`

1555 

1556 A tool that allows the model to execute shell commands.

1557 

1558 - `type: "shell"`

1559 

1560 The type of the shell tool. Always `shell`.

1561 

1562 - `"shell"`

1563 

1564 - `environment: optional ContainerAuto or LocalEnvironment or ContainerReference`

1565 

1566 - `ContainerAuto object { type, file_ids, memory_limit, 2 more }`

1567 

1568 - `type: "container_auto"`

1569 

1570 Automatically creates a container for this request

1571 

1572 - `"container_auto"`

1573 

1574 - `file_ids: optional array of string`

1575 

1576 An optional list of uploaded files to make available to your code.

1577 

1578 - `memory_limit: optional "1g" or "4g" or "16g" or "64g"`

1579 

1580 The memory limit for the container.

1581 

1582 - `"1g"`

1583 

1584 - `"4g"`

1585 

1586 - `"16g"`

1587 

1588 - `"64g"`

1589 

1590 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1591 

1592 Network access policy for the container.

1593 

1594 - `ContainerNetworkPolicyDisabled object { type }`

1595 

1596 - `ContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }`

1597 

1598 - `skills: optional array of SkillReference or InlineSkill`

1599 

1600 An optional list of skills referenced by id or inline data.

1601 

1602 - `SkillReference object { skill_id, type, version }`

1603 

1604 - `skill_id: string`

1605 

1606 The ID of the referenced skill.

1607 

1608 - `type: "skill_reference"`

1609 

1610 References a skill created with the /v1/skills endpoint.

1611 

1612 - `"skill_reference"`

1613 

1614 - `version: optional string`

1615 

1616 Optional skill version. Use a positive integer or 'latest'. Omit for default.

1617 

1618 - `InlineSkill object { description, name, source, type }`

1619 

1620 - `description: string`

1621 

1622 The description of the skill.

1623 

1624 - `name: string`

1625 

1626 The name of the skill.

1627 

1628 - `source: InlineSkillSource`

1629 

1630 Inline skill payload

1631 

1632 - `data: string`

1633 

1634 Base64-encoded skill zip bundle.

1635 

1636 - `media_type: "application/zip"`

1637 

1638 The media type of the inline skill payload. Must be `application/zip`.

1639 

1640 - `"application/zip"`

1641 

1642 - `type: "base64"`

1643 

1644 The type of the inline skill source. Must be `base64`.

1645 

1646 - `"base64"`

1647 

1648 - `type: "inline"`

1649 

1650 Defines an inline skill for this request.

1651 

1652 - `"inline"`

1653 

1654 - `LocalEnvironment object { type, skills }`

1655 

1656 - `type: "local"`

1657 

1658 Use a local computer environment.

1659 

1660 - `"local"`

1661 

1662 - `skills: optional array of LocalSkill`

1663 

1664 An optional list of skills.

1665 

1666 - `description: string`

1667 

1668 The description of the skill.

1669 

1670 - `name: string`

1671 

1672 The name of the skill.

1673 

1674 - `path: string`

1675 

1676 The path to the directory containing the skill.

1677 

1678 - `ContainerReference object { container_id, type }`

1679 

1680 - `container_id: string`

1681 

1682 The ID of the referenced container.

1683 

1684 - `type: "container_reference"`

1685 

1686 References a container created with the /v1/containers endpoint

1687 

1688 - `"container_reference"`

1689 

1690 - `Custom object { name, type, defer_loading, 2 more }`

1691 

1692 A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools)

1693 

1694 - `name: string`

1695 

1696 The name of the custom tool, used to identify it in tool calls.

1697 

1698 - `type: "custom"`

1699 

1700 The type of the custom tool. Always `custom`.

1701 

1702 - `"custom"`

1703 

1704 - `defer_loading: optional boolean`

1705 

1706 Whether this tool should be deferred and discovered via tool search.

1707 

1708 - `description: optional string`

1709 

1710 Optional description of the custom tool, used to provide more context.

1711 

1712 - `format: optional CustomToolInputFormat`

1713 

1714 The input format for the custom tool. Default is unconstrained text.

1715 

1716 - `Text object { type }`

1717 

1718 Unconstrained free-form text.

1719 

1720 - `type: "text"`

1721 

1722 Unconstrained text format. Always `text`.

1723 

1724 - `"text"`

1725 

1726 - `Grammar object { definition, syntax, type }`

1727 

1728 A grammar defined by the user.

1729 

1730 - `definition: string`

1731 

1732 The grammar definition.

1733 

1734 - `syntax: "lark" or "regex"`

1735 

1736 The syntax of the grammar definition. One of `lark` or `regex`.

1737 

1738 - `"lark"`

1739 

1740 - `"regex"`

1741 

1742 - `type: "grammar"`

1743 

1744 Grammar format. Always `grammar`.

1745 

1746 - `"grammar"`

1747 

1748 - `Namespace object { description, name, tools, type }`

1749 

1750 Groups function/custom tools under a shared namespace.

1751 

1752 - `description: string`

1753 

1754 A description of the namespace shown to the model.

1755 

1756 - `name: string`

1757 

1758 The namespace name used in tool calls (for example, `crm`).

1759 

1760 - `tools: array of object { name, type, defer_loading, 3 more } or object { name, type, defer_loading, 2 more }`

1761 

1762 The function/custom tools available inside this namespace.

1763 

1764 - `Function object { name, type, defer_loading, 3 more }`

1765 

1766 - `name: string`

1767 

1768 - `type: "function"`

1769 

1770 - `"function"`

1771 

1772 - `defer_loading: optional boolean`

1773 

1774 Whether this function should be deferred and discovered via tool search.

1775 

1776 - `description: optional string`

1777 

1778 - `parameters: optional unknown`

1779 

1780 - `strict: optional boolean`

1781 

1782 - `Custom object { name, type, defer_loading, 2 more }`

1783 

1784 A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools)

1785 

1786 - `name: string`

1787 

1788 The name of the custom tool, used to identify it in tool calls.

1789 

1790 - `type: "custom"`

1791 

1792 The type of the custom tool. Always `custom`.

1793 

1794 - `"custom"`

1795 

1796 - `defer_loading: optional boolean`

1797 

1798 Whether this tool should be deferred and discovered via tool search.

1799 

1800 - `description: optional string`

1801 

1802 Optional description of the custom tool, used to provide more context.

1803 

1804 - `format: optional CustomToolInputFormat`

1805 

1806 The input format for the custom tool. Default is unconstrained text.

1807 

1808 - `type: "namespace"`

1809 

1810 The type of the tool. Always `namespace`.

1811 

1812 - `"namespace"`

1813 

1814 - `ToolSearch object { type, description, execution, parameters }`

1815 

1816 Hosted or BYOT tool search configuration for deferred tools.

1817 

1818 - `type: "tool_search"`

1819 

1820 The type of the tool. Always `tool_search`.

1821 

1822 - `"tool_search"`

1823 

1824 - `description: optional string`

1825 

1826 Description shown to the model for a client-executed tool search tool.

1827 

1828 - `execution: optional "server" or "client"`

1829 

1830 Whether tool search is executed by the server or by the client.

1831 

1832 - `"server"`

1833 

1834 - `"client"`

1835 

1836 - `parameters: optional unknown`

1837 

1838 Parameter schema for a client-executed tool search tool.

1839 

1840 - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }`

1841 

1842 This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search).

1843 

1844 - `type: "web_search_preview" or "web_search_preview_2025_03_11"`

1845 

1846 The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`.

1847 

1848 - `"web_search_preview"`

1849 

1850 - `"web_search_preview_2025_03_11"`

1851 

1852 - `search_content_types: optional array of "text" or "image"`

1853 

1854 - `"text"`

1855 

1856 - `"image"`

1857 

1858 - `search_context_size: optional "low" or "medium" or "high"`

1859 

1860 High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default.

1861 

1862 - `"low"`

1863 

1864 - `"medium"`

1865 

1866 - `"high"`

1867 

1868 - `user_location: optional object { type, city, country, 2 more }`

1869 

1870 The user's location.

1871 

1872 - `type: "approximate"`

1873 

1874 The type of location approximation. Always `approximate`.

1875 

1876 - `"approximate"`

1877 

1878 - `city: optional string`

1879 

1880 Free text input for the city of the user, e.g. `San Francisco`.

1881 

1882 - `country: optional string`

1883 

1884 The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`.

1885 

1886 - `region: optional string`

1887 

1888 Free text input for the region of the user, e.g. `California`.

1889 

1890 - `timezone: optional string`

1891 

1892 The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`.

1893 

1894 - `ApplyPatch object { type }`

1895 

1896 Allows the assistant to create, delete, or update files using unified diffs.

1897 

1898 - `type: "apply_patch"`

1899 

1900 The type of the tool. Always `apply_patch`.

1901 

1902 - `"apply_patch"`

1903 

1904 - `top_p: optional number`

1905 

1906 An alternative to temperature for nucleus sampling; 1.0 includes all tokens.

1907 

1908- `error: EvalAPIError`

1909 

1910 An object representing an error response from the Eval API.

1911 

1912 - `code: string`

1913 

1914 The error code.

1915 

1916 - `message: string`

1917 

1918 The error message.

1919 

1920- `eval_id: string`

1921 

1922 The identifier of the associated evaluation.

1923 

1924- `metadata: Metadata`

1925 

1926 Set of 16 key-value pairs that can be attached to an object. This can be

1927 useful for storing additional information about the object in a structured

1928 format, and querying for objects via API or the dashboard.

1929 

1930 Keys are strings with a maximum length of 64 characters. Values are strings

1931 with a maximum length of 512 characters.

1932 

1933- `model: string`

1934 

1935 The model that is evaluated, if applicable.

1936 

1937- `name: string`

1938 

1939 The name of the evaluation run.

1940 

1941- `object: "eval.run"`

1942 

1943 The type of the object. Always "eval.run".

1944 

1945 - `"eval.run"`

1946 

1947- `per_model_usage: array of object { cached_tokens, completion_tokens, invocation_count, 3 more }`

1948 

1949 Usage statistics for each model during the evaluation run.

1950 

1951 - `cached_tokens: number`

1952 

1953 The number of tokens retrieved from cache.

1954 

1955 - `completion_tokens: number`

1956 

1957 The number of completion tokens generated.

1958 

1959 - `invocation_count: number`

1960 

1961 The number of invocations.

1962 

1963 - `model_name: string`

1964 

1965 The name of the model.

1966 

1967 - `prompt_tokens: number`

1968 

1969 The number of prompt tokens used.

1970 

1971 - `total_tokens: number`

1972 

1973 The total number of tokens used.

1974 

1975- `per_testing_criteria_results: array of object { failed, passed, testing_criteria }`

1976 

1977 Results per testing criteria applied during the evaluation run.

1978 

1979 - `failed: number`

1980 

1981 Number of tests failed for this criteria.

1982 

1983 - `passed: number`

1984 

1985 Number of tests passed for this criteria.

1986 

1987 - `testing_criteria: string`

1988 

1989 A description of the testing criteria.

1990 

1991- `report_url: string`

1992 

1993 The URL to the rendered evaluation run report on the UI dashboard.

1994 

1995- `result_counts: object { errored, failed, passed, total }`

1996