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

1## Create eval run

2 

3**post** `/evals/{eval_id}/runs`

4 

5Kicks off a new run for a given evaluation, specifying the data source, and what model configuration to use to test. The datasource will be validated against the schema specified in the config of the evaluation.

6 

7### Path Parameters

8 

9- `eval_id: string`

10 

11### Body Parameters

12 

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

14 

15 Details about the run's data source.

16 

17 - `CreateEvalJSONLRunDataSource object { source, type }`

18 

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

20 

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

22 

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

24 

25 - `EvalJSONLFileContentSource object { content, type }`

26 

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

28 

29 The content of the jsonl file.

30 

31 - `item: map[unknown]`

32 

33 - `sample: optional map[unknown]`

34 

35 - `type: "file_content"`

36 

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

38 

39 - `"file_content"`

40 

41 - `EvalJSONLFileIDSource object { id, type }`

42 

43 - `id: string`

44 

45 The identifier of the file.

46 

47 - `type: "file_id"`

48 

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

50 

51 - `"file_id"`

52 

53 - `type: "jsonl"`

54 

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

56 

57 - `"jsonl"`

58 

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

60 

61 A CompletionsRunDataSource object describing a model sampling configuration.

62 

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

64 

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

66 

67 - `EvalJSONLFileContentSource object { content, type }`

68 

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

70 

71 The content of the jsonl file.

72 

73 - `item: map[unknown]`

74 

75 - `sample: optional map[unknown]`

76 

77 - `type: "file_content"`

78 

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

80 

81 - `"file_content"`

82 

83 - `EvalJSONLFileIDSource object { id, type }`

84 

85 - `id: string`

86 

87 The identifier of the file.

88 

89 - `type: "file_id"`

90 

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

92 

93 - `"file_id"`

94 

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

96 

97 A StoredCompletionsRunDataSource configuration describing a set of filters

98 

99 - `type: "stored_completions"`

100 

101 The type of source. Always `stored_completions`.

102 

103 - `"stored_completions"`

104 

105 - `created_after: optional number`

106 

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

108 

109 - `created_before: optional number`

110 

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

112 

113 - `limit: optional number`

114 

115 An optional maximum number of items to return.

116 

117 - `metadata: optional Metadata`

118 

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

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

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

122 

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

124 with a maximum length of 512 characters.

125 

126 - `model: optional string`

127 

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

129 

130 - `type: "completions"`

131 

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

133 

134 - `"completions"`

135 

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

137 

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

139 

140 - `TemplateInputMessages object { template, type }`

141 

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

143 

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

145 

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

147 

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

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

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

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

152 interactions.

153 

154 - `content: string or ResponseInputMessageContentList`

155 

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

157 Can also contain previous assistant responses.

158 

159 - `TextInput = string`

160 

161 A text input to the model.

162 

163 - `ResponseInputMessageContentList = array of ResponseInputContent`

164 

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

166 types.

167 

168 - `ResponseInputText object { text, type }`

169 

170 A text input to the model.

171 

172 - `text: string`

173 

174 The text input to the model.

175 

176 - `type: "input_text"`

177 

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

179 

180 - `"input_text"`

181 

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

183 

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

185 

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

187 

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

189 

190 - `"low"`

191 

192 - `"high"`

193 

194 - `"auto"`

195 

196 - `"original"`

197 

198 - `type: "input_image"`

199 

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

201 

202 - `"input_image"`

203 

204 - `file_id: optional string`

205 

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

207 

208 - `image_url: optional string`

209 

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

211 

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

213 

214 A file input to the model.

215 

216 - `type: "input_file"`

217 

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

219 

220 - `"input_file"`

221 

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

223 

224 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`.

225 

226 - `"low"`

227 

228 - `"high"`

229 

230 - `file_data: optional string`

231 

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

233 

234 - `file_id: optional string`

235 

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

237 

238 - `file_url: optional string`

239 

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

241 

242 - `filename: optional string`

243 

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

245 

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

247 

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

249 `developer`.

250 

251 - `"user"`

252 

253 - `"assistant"`

254 

255 - `"system"`

256 

257 - `"developer"`

258 

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

260 

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

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

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

264 

265 - `"commentary"`

266 

267 - `"final_answer"`

268 

269 - `type: optional "message"`

270 

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

272 

273 - `"message"`

274 

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

276 

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

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

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

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

281 interactions.

282 

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

284 

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

286 

287 - `TextInput = string`

288 

289 A text input to the model.

290 

291 - `ResponseInputText object { text, type }`

292 

293 A text input to the model.

294 

295 - `OutputText object { text, type }`

296 

297 A text output from the model.

298 

299 - `text: string`

300 

301 The text output from the model.

302 

303 - `type: "output_text"`

304 

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

306 

307 - `"output_text"`

308 

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

310 

311 An image input block used within EvalItem content arrays.

312 

313 - `image_url: string`

314 

315 The URL of the image input.

316 

317 - `type: "input_image"`

318 

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

320 

321 - `"input_image"`

322 

323 - `detail: optional string`

324 

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

326 

327 - `ResponseInputAudio object { input_audio, type }`

328 

329 An audio input to the model.

330 

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

332 

333 - `data: string`

334 

335 Base64-encoded audio data.

336 

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

338 

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

340 `wav`.

341 

342 - `"mp3"`

343 

344 - `"wav"`

345 

346 - `type: "input_audio"`

347 

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

349 

350 - `"input_audio"`

351 

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

353 

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

355 image, or input audio object.

356 

357 - `TextInput = string`

358 

359 A text input to the model.

360 

361 - `ResponseInputText object { text, type }`

362 

363 A text input to the model.

364 

365 - `OutputText object { text, type }`

366 

367 A text output from the model.

368 

369 - `text: string`

370 

371 The text output from the model.

372 

373 - `type: "output_text"`

374 

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

376 

377 - `"output_text"`

378 

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

380 

381 An image input block used within EvalItem content arrays.

382 

383 - `image_url: string`

384 

385 The URL of the image input.

386 

387 - `type: "input_image"`

388 

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

390 

391 - `"input_image"`

392 

393 - `detail: optional string`

394 

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

396 

397 - `ResponseInputAudio object { input_audio, type }`

398 

399 An audio input to the model.

400 

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

402 

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

404 `developer`.

405 

406 - `"user"`

407 

408 - `"assistant"`

409 

410 - `"system"`

411 

412 - `"developer"`

413 

414 - `type: optional "message"`

415 

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

417 

418 - `"message"`

419 

420 - `type: "template"`

421 

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

423 

424 - `"template"`

425 

426 - `ItemReferenceInputMessages object { item_reference, type }`

427 

428 - `item_reference: string`

429 

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

431 

432 - `type: "item_reference"`

433 

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

435 

436 - `"item_reference"`

437 

438 - `model: optional string`

439 

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

441 

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

443 

444 - `max_completion_tokens: optional number`

445 

446 The maximum number of tokens in the generated output.

447 

448 - `reasoning_effort: optional ReasoningEffort`

449 

450 Constrains effort on reasoning for

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

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

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

454 on reasoning in a response.

455 

456 - `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.

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

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

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

460 

461 - `"none"`

462 

463 - `"minimal"`

464 

465 - `"low"`

466 

467 - `"medium"`

468 

469 - `"high"`

470 

471 - `"xhigh"`

472 

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

474 

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

476 

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

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

479 schema. Learn more in the [Structured Outputs

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

481 

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

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

484 is preferred for models that support it.

485 

486 - `ResponseFormatText object { type }`

487 

488 Default response format. Used to generate text responses.

489 

490 - `type: "text"`

491 

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

493 

494 - `"text"`

495 

496 - `ResponseFormatJSONSchema object { json_schema, type }`

497 

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

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

500 

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

502 

503 Structured Outputs configuration options, including a JSON Schema.

504 

505 - `name: string`

506 

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

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

509 

510 - `description: optional string`

511 

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

513 determine how to respond in the format.

514 

515 - `schema: optional map[unknown]`

516 

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

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

519 

520 - `strict: optional boolean`

521 

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

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

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

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

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

527 

528 - `type: "json_schema"`

529 

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

531 

532 - `"json_schema"`

533 

534 - `ResponseFormatJSONObject object { type }`

535 

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

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

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

539 to do so.

540 

541 - `type: "json_object"`

542 

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

544 

545 - `"json_object"`

546 

547 - `seed: optional number`

548 

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

550 

551 - `temperature: optional number`

552 

553 A higher temperature increases randomness in the outputs.

554 

555 - `tools: optional array of ChatCompletionFunctionTool`

556 

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

558 

559 - `function: FunctionDefinition`

560 

561 - `name: string`

562 

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

564 

565 - `description: optional string`

566 

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

568 

569 - `parameters: optional FunctionParameters`

570 

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

572 

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

574 

575 - `strict: optional boolean`

576 

577 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).

578 

579 - `type: "function"`

580 

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

582 

583 - `"function"`

584 

585 - `top_p: optional number`

586 

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

588 

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

590 

591 A ResponsesRunDataSource object describing a model sampling configuration.

592 

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

594 

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

596 

597 - `EvalJSONLFileContentSource object { content, type }`

598 

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

600 

601 The content of the jsonl file.

602 

603 - `item: map[unknown]`

604 

605 - `sample: optional map[unknown]`

606 

607 - `type: "file_content"`

608 

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

610 

611 - `"file_content"`

612 

613 - `EvalJSONLFileIDSource object { id, type }`

614 

615 - `id: string`

616 

617 The identifier of the file.

618 

619 - `type: "file_id"`

620 

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

622 

623 - `"file_id"`

624 

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

626 

627 A EvalResponsesSource object describing a run data source configuration.

628 

629 - `type: "responses"`

630 

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

632 

633 - `"responses"`

634 

635 - `created_after: optional number`

636 

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

638 

639 - `created_before: optional number`

640 

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

642 

643 - `instructions_search: optional string`

644 

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

646 

647 - `metadata: optional unknown`

648 

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

650 

651 - `model: optional string`

652 

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

654 

655 - `reasoning_effort: optional ReasoningEffort`

656 

657 Constrains effort on reasoning for

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

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

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

661 on reasoning in a response.

662 

663 - `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.

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

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

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

667 

668 - `temperature: optional number`

669 

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

671 

672 - `tools: optional array of string`

673 

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

675 

676 - `top_p: optional number`

677 

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

679 

680 - `users: optional array of string`

681 

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

683 

684 - `type: "responses"`

685 

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

687 

688 - `"responses"`

689 

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

691 

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

693 

694 - `InputMessagesTemplate object { template, type }`

695 

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

697 

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

699 

700 - `ChatMessage object { content, role }`

701 

702 - `content: string`

703 

704 The content of the message.

705 

706 - `role: string`

707 

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

709 

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

711 

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

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

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

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

716 interactions.

717 

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

719 

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

721 

722 - `TextInput = string`

723 

724 A text input to the model.

725 

726 - `ResponseInputText object { text, type }`

727 

728 A text input to the model.

729 

730 - `OutputText object { text, type }`

731 

732 A text output from the model.

733 

734 - `text: string`

735 

736 The text output from the model.

737 

738 - `type: "output_text"`

739 

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

741 

742 - `"output_text"`

743 

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

745 

746 An image input block used within EvalItem content arrays.

747 

748 - `image_url: string`

749 

750 The URL of the image input.

751 

752 - `type: "input_image"`

753 

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

755 

756 - `"input_image"`

757 

758 - `detail: optional string`

759 

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

761 

762 - `ResponseInputAudio object { input_audio, type }`

763 

764 An audio input to the model.

765 

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

767 

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

769 image, or input audio object.

770 

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

772 

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

774 `developer`.

775 

776 - `"user"`

777 

778 - `"assistant"`

779 

780 - `"system"`

781 

782 - `"developer"`

783 

784 - `type: optional "message"`

785 

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

787 

788 - `"message"`

789 

790 - `type: "template"`

791 

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

793 

794 - `"template"`

795 

796 - `InputMessagesItemReference object { item_reference, type }`

797 

798 - `item_reference: string`

799 

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

801 

802 - `type: "item_reference"`

803 

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

805 

806 - `"item_reference"`

807 

808 - `model: optional string`

809 

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

811 

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

813 

814 - `max_completion_tokens: optional number`

815 

816 The maximum number of tokens in the generated output.

817 

818 - `reasoning_effort: optional ReasoningEffort`

819 

820 Constrains effort on reasoning for

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

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

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

824 on reasoning in a response.

825 

826 - `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.

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

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

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

830 

831 - `seed: optional number`

832 

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

834 

835 - `temperature: optional number`

836 

837 A higher temperature increases randomness in the outputs.

838 

839 - `text: optional object { format }`

840 

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

842 text or structured JSON data. Learn more:

843 

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

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

846 

847 - `format: optional ResponseFormatTextConfig`

848 

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

850 

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

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

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

854 

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

856 

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

858 

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

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

861 is preferred for models that support it.

862 

863 - `ResponseFormatText object { type }`

864 

865 Default response format. Used to generate text responses.

866 

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

868 

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

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

871 

872 - `name: string`

873 

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

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

876 

877 - `schema: map[unknown]`

878 

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

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

881 

882 - `type: "json_schema"`

883 

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

885 

886 - `"json_schema"`

887 

888 - `description: optional string`

889 

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

891 determine how to respond in the format.

892 

893 - `strict: optional boolean`

894 

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

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

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

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

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

900 

901 - `ResponseFormatJSONObject object { type }`

902 

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

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

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

906 to do so.

907 

908 - `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`

909 

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

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

912 

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

914 

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

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

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

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

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

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

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

922 

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

924 

925 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).

926 

927 - `name: string`

928 

929 The name of the function to call.

930 

931 - `parameters: map[unknown]`

932 

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

934 

935 - `strict: boolean`

936 

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

938 

939 - `type: "function"`

940 

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

942 

943 - `"function"`

944 

945 - `defer_loading: optional boolean`

946 

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

948 

949 - `description: optional string`

950 

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

952 

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

954 

955 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).

956 

957 - `type: "file_search"`

958 

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

960 

961 - `"file_search"`

962 

963 - `vector_store_ids: array of string`

964 

965 The IDs of the vector stores to search.

966 

967 - `filters: optional ComparisonFilter or CompoundFilter`

968 

969 A filter to apply.

970 

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

972 

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

974 

975 - `key: string`

976 

977 The key to compare against the value.

978 

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

980 

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

982 

983 - `eq`: equals

984 - `ne`: not equal

985 - `gt`: greater than

986 - `gte`: greater than or equal

987 - `lt`: less than

988 - `lte`: less than or equal

989 - `in`: in

990 - `nin`: not in

991 

992 - `"eq"`

993 

994 - `"ne"`

995 

996 - `"gt"`

997 

998 - `"gte"`

999 

1000 - `"lt"`

1001 

1002 - `"lte"`

1003 

1004 - `"in"`

1005 

1006 - `"nin"`

1007 

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

1009 

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

1011 

1012 - `string`

1013 

1014 - `number`

1015 

1016 - `boolean`

1017 

1018 - `array of string or number`

1019 

1020 - `string`

1021 

1022 - `number`

1023 

1024 - `CompoundFilter object { filters, type }`

1025 

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

1027 

1028 - `filters: array of ComparisonFilter or unknown`

1029 

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

1031 

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

1033 

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

1035 

1036 - `unknown`

1037 

1038 - `type: "and" or "or"`

1039 

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

1041 

1042 - `"and"`

1043 

1044 - `"or"`

1045 

1046 - `max_num_results: optional number`

1047 

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

1049 

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

1051 

1052 Ranking options for search.

1053 

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

1055 

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

1057 

1058 - `embedding_weight: number`

1059 

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

1061 

1062 - `text_weight: number`

1063 

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

1065 

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

1067 

1068 The ranker to use for the file search.

1069 

1070 - `"auto"`

1071 

1072 - `"default-2024-11-15"`

1073 

1074 - `score_threshold: optional number`

1075 

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

1077 

1078 - `Computer object { type }`

1079 

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

1081 

1082 - `type: "computer"`

1083 

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

1085 

1086 - `"computer"`

1087 

1088 - `ComputerUsePreview object { display_height, display_width, environment, 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 - `display_height: number`

1093 

1094 The height of the computer display.

1095 

1096 - `display_width: number`

1097 

1098 The width of the computer display.

1099 

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

1101 

1102 The type of computer environment to control.

1103 

1104 - `"windows"`

1105 

1106 - `"mac"`

1107 

1108 - `"linux"`

1109 

1110 - `"ubuntu"`

1111 

1112 - `"browser"`

1113 

1114 - `type: "computer_use_preview"`

1115 

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

1117 

1118 - `"computer_use_preview"`

1119 

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

1121 

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

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

1124 

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

1126 

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

1128 

1129 - `"web_search"`

1130 

1131 - `"web_search_2025_08_26"`

1132 

1133 - `filters: optional object { allowed_domains }`

1134 

1135 Filters for the search.

1136 

1137 - `allowed_domains: optional array of string`

1138 

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

1140 Subdomains of the provided domains are allowed as well.

1141 

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

1143 

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

1145 

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

1147 

1148 - `"low"`

1149 

1150 - `"medium"`

1151 

1152 - `"high"`

1153 

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

1155 

1156 The approximate location of the user.

1157 

1158 - `city: optional string`

1159 

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

1161 

1162 - `country: optional string`

1163 

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

1165 

1166 - `region: optional string`

1167 

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

1169 

1170 - `timezone: optional string`

1171 

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

1173 

1174 - `type: optional "approximate"`

1175 

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

1177 

1178 - `"approximate"`

1179 

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

1181 

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

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

1184 

1185 - `server_label: string`

1186 

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

1188 

1189 - `type: "mcp"`

1190 

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

1192 

1193 - `"mcp"`

1194 

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

1196 

1197 List of allowed tool names or a filter object.

1198 

1199 - `McpAllowedTools = array of string`

1200 

1201 A string array of allowed tool names

1202 

1203 - `McpToolFilter object { read_only, tool_names }`

1204 

1205 A filter object to specify which tools are allowed.

1206 

1207 - `read_only: optional boolean`

1208 

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

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

1211 it will match this filter.

1212 

1213 - `tool_names: optional array of string`

1214 

1215 List of allowed tool names.

1216 

1217 - `authorization: optional string`

1218 

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

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

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

1222 

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

1224 

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

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

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

1228 

1229 Currently supported `connector_id` values are:

1230 

1231 - Dropbox: `connector_dropbox`

1232 - Gmail: `connector_gmail`

1233 - Google Calendar: `connector_googlecalendar`

1234 - Google Drive: `connector_googledrive`

1235 - Microsoft Teams: `connector_microsoftteams`

1236 - Outlook Calendar: `connector_outlookcalendar`

1237 - Outlook Email: `connector_outlookemail`

1238 - SharePoint: `connector_sharepoint`

1239 

1240 - `"connector_dropbox"`

1241 

1242 - `"connector_gmail"`

1243 

1244 - `"connector_googlecalendar"`

1245 

1246 - `"connector_googledrive"`

1247 

1248 - `"connector_microsoftteams"`

1249 

1250 - `"connector_outlookcalendar"`

1251 

1252 - `"connector_outlookemail"`

1253 

1254 - `"connector_sharepoint"`

1255 

1256 - `defer_loading: optional boolean`

1257 

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

1259 

1260 - `headers: optional map[string]`

1261 

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

1263 or other purposes.

1264 

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

1266 

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

1268 

1269 - `McpToolApprovalFilter object { always, never }`

1270 

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

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

1273 that require approval.

1274 

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

1276 

1277 A filter object to specify which tools are allowed.

1278 

1279 - `read_only: optional boolean`

1280 

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

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

1283 it will match this filter.

1284 

1285 - `tool_names: optional array of string`

1286 

1287 List of allowed tool names.

1288 

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

1290 

1291 A filter object to specify which tools are allowed.

1292 

1293 - `read_only: optional boolean`

1294 

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

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

1297 it will match this filter.

1298 

1299 - `tool_names: optional array of string`

1300 

1301 List of allowed tool names.

1302 

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

1304 

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

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

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

1308 

1309 - `"always"`

1310 

1311 - `"never"`

1312 

1313 - `server_description: optional string`

1314 

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

1316 

1317 - `server_url: optional string`

1318 

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

1320 provided.

1321 

1322 - `CodeInterpreter object { container, type }`

1323 

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

1325 

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

1327 

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

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

1330 optional `memory_limit` setting.

1331 

1332 - `string`

1333 

1334 The container ID.

1335 

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

1337 

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

1339 

1340 - `type: "auto"`

1341 

1342 Always `auto`.

1343 

1344 - `"auto"`

1345 

1346 - `file_ids: optional array of string`

1347 

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

1349 

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

1351 

1352 The memory limit for the code interpreter container.

1353 

1354 - `"1g"`

1355 

1356 - `"4g"`

1357 

1358 - `"16g"`

1359 

1360 - `"64g"`

1361 

1362 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1363 

1364 Network access policy for the container.

1365 

1366 - `ContainerNetworkPolicyDisabled object { type }`

1367 

1368 - `type: "disabled"`

1369 

1370 Disable outbound network access. Always `disabled`.

1371 

1372 - `"disabled"`

1373 

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

1375 

1376 - `allowed_domains: array of string`

1377 

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

1379 

1380 - `type: "allowlist"`

1381 

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

1383 

1384 - `"allowlist"`

1385 

1386 - `domain_secrets: optional array of ContainerNetworkPolicyDomainSecret`

1387 

1388 Optional domain-scoped secrets for allowlisted domains.

1389 

1390 - `domain: string`

1391 

1392 The domain associated with the secret.

1393 

1394 - `name: string`

1395 

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

1397 

1398 - `value: string`

1399 

1400 The secret value to inject for the domain.

1401 

1402 - `type: "code_interpreter"`

1403 

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

1405 

1406 - `"code_interpreter"`

1407 

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

1409 

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

1411 

1412 - `type: "image_generation"`

1413 

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

1415 

1416 - `"image_generation"`

1417 

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

1419 

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

1421 

1422 - `"generate"`

1423 

1424 - `"edit"`

1425 

1426 - `"auto"`

1427 

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

1429 

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

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

1432 

1433 - `"transparent"`

1434 

1435 - `"opaque"`

1436 

1437 - `"auto"`

1438 

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

1440 

1441 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`.

1442 

1443 - `"high"`

1444 

1445 - `"low"`

1446 

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

1448 

1449 Optional mask for inpainting. Contains `image_url`

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

1451 

1452 - `file_id: optional string`

1453 

1454 File ID for the mask image.

1455 

1456 - `image_url: optional string`

1457 

1458 Base64-encoded mask image.

1459 

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

1461 

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

1463 

1464 - `string`

1465 

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

1467 

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

1469 

1470 - `"gpt-image-1"`

1471 

1472 - `"gpt-image-1-mini"`

1473 

1474 - `"gpt-image-1.5"`

1475 

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

1477 

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

1479 

1480 - `"auto"`

1481 

1482 - `"low"`

1483 

1484 - `output_compression: optional number`

1485 

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

1487 

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

1489 

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

1491 `jpeg`. Default: `png`.

1492 

1493 - `"png"`

1494 

1495 - `"webp"`

1496 

1497 - `"jpeg"`

1498 

1499 - `partial_images: optional number`

1500 

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

1502 

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

1504 

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

1506 or `auto`. Default: `auto`.

1507 

1508 - `"low"`

1509 

1510 - `"medium"`

1511 

1512 - `"high"`

1513 

1514 - `"auto"`

1515 

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

1517 

1518 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`.

1519 

1520 - `string`

1521 

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

1523 

1524 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`.

1525 

1526 - `"1024x1024"`

1527 

1528 - `"1024x1536"`

1529 

1530 - `"1536x1024"`

1531 

1532 - `"auto"`

1533 

1534 - `LocalShell object { type }`

1535 

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

1537 

1538 - `type: "local_shell"`

1539 

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

1541 

1542 - `"local_shell"`

1543 

1544 - `Shell object { type, environment }`

1545 

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

1547 

1548 - `type: "shell"`

1549 

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

1551 

1552 - `"shell"`

1553 

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

1555 

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

1557 

1558 - `type: "container_auto"`

1559 

1560 Automatically creates a container for this request

1561 

1562 - `"container_auto"`

1563 

1564 - `file_ids: optional array of string`

1565 

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

1567 

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

1569 

1570 The memory limit for the container.

1571 

1572 - `"1g"`

1573 

1574 - `"4g"`

1575 

1576 - `"16g"`

1577 

1578 - `"64g"`

1579 

1580 - `network_policy: optional ContainerNetworkPolicyDisabled or ContainerNetworkPolicyAllowlist`

1581 

1582 Network access policy for the container.

1583 

1584 - `ContainerNetworkPolicyDisabled object { type }`

1585 

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

1587 

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

1589 

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

1591 

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

1593 

1594 - `skill_id: string`

1595 

1596 The ID of the referenced skill.

1597 

1598 - `type: "skill_reference"`

1599 

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

1601 

1602 - `"skill_reference"`

1603 

1604 - `version: optional string`

1605 

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

1607 

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

1609 

1610 - `description: string`

1611 

1612 The description of the skill.

1613 

1614 - `name: string`

1615 

1616 The name of the skill.

1617 

1618 - `source: InlineSkillSource`

1619 

1620 Inline skill payload

1621 

1622 - `data: string`

1623 

1624 Base64-encoded skill zip bundle.

1625 

1626 - `media_type: "application/zip"`

1627 

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

1629 

1630 - `"application/zip"`

1631 

1632 - `type: "base64"`

1633 

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

1635 

1636 - `"base64"`

1637 

1638 - `type: "inline"`

1639 

1640 Defines an inline skill for this request.

1641 

1642 - `"inline"`

1643 

1644 - `LocalEnvironment object { type, skills }`

1645 

1646 - `type: "local"`

1647 

1648 Use a local computer environment.

1649 

1650 - `"local"`

1651 

1652 - `skills: optional array of LocalSkill`

1653 

1654 An optional list of skills.

1655 

1656 - `description: string`

1657 

1658 The description of the skill.

1659 

1660 - `name: string`

1661 

1662 The name of the skill.

1663 

1664 - `path: string`

1665 

1666 The path to the directory containing the skill.

1667 

1668 - `ContainerReference object { container_id, type }`

1669 

1670 - `container_id: string`

1671 

1672 The ID of the referenced container.

1673 

1674 - `type: "container_reference"`

1675 

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

1677 

1678 - `"container_reference"`

1679 

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

1681 

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

1683 

1684 - `name: string`

1685 

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

1687 

1688 - `type: "custom"`

1689 

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

1691 

1692 - `"custom"`

1693 

1694 - `defer_loading: optional boolean`

1695 

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

1697 

1698 - `description: optional string`

1699 

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

1701 

1702 - `format: optional CustomToolInputFormat`

1703 

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

1705 

1706 - `Text object { type }`

1707 

1708 Unconstrained free-form text.

1709 

1710 - `type: "text"`

1711 

1712 Unconstrained text format. Always `text`.

1713 

1714 - `"text"`

1715 

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

1717 

1718 A grammar defined by the user.

1719 

1720 - `definition: string`

1721 

1722 The grammar definition.

1723 

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

1725 

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

1727 

1728 - `"lark"`

1729 

1730 - `"regex"`

1731 

1732 - `type: "grammar"`

1733 

1734 Grammar format. Always `grammar`.

1735 

1736 - `"grammar"`

1737 

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

1739 

1740 Groups function/custom tools under a shared namespace.

1741 

1742 - `description: string`

1743 

1744 A description of the namespace shown to the model.

1745 

1746 - `name: string`

1747 

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

1749 

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

1751 

1752 The function/custom tools available inside this namespace.

1753 

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

1755 

1756 - `name: string`

1757 

1758 - `type: "function"`

1759 

1760 - `"function"`

1761 

1762 - `defer_loading: optional boolean`

1763 

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

1765 

1766 - `description: optional string`

1767 

1768 - `parameters: optional unknown`

1769 

1770 - `strict: optional boolean`

1771 

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

1773 

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

1775 

1776 - `name: string`

1777 

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

1779 

1780 - `type: "custom"`

1781 

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

1783 

1784 - `"custom"`

1785 

1786 - `defer_loading: optional boolean`

1787 

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

1789 

1790 - `description: optional string`

1791 

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

1793 

1794 - `format: optional CustomToolInputFormat`

1795 

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

1797 

1798 - `type: "namespace"`

1799 

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

1801 

1802 - `"namespace"`

1803 

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

1805 

1806 Hosted or BYOT tool search configuration for deferred tools.

1807 

1808 - `type: "tool_search"`

1809 

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

1811 

1812 - `"tool_search"`

1813 

1814 - `description: optional string`

1815 

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

1817 

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

1819 

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

1821 

1822 - `"server"`

1823 

1824 - `"client"`

1825 

1826 - `parameters: optional unknown`

1827 

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

1829 

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

1831 

1832 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).

1833 

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

1835 

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

1837 

1838 - `"web_search_preview"`

1839 

1840 - `"web_search_preview_2025_03_11"`

1841 

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

1843 

1844 - `"text"`

1845 

1846 - `"image"`

1847 

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

1849 

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

1851 

1852 - `"low"`

1853 

1854 - `"medium"`

1855 

1856 - `"high"`

1857 

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

1859 

1860 The user's location.

1861 

1862 - `type: "approximate"`

1863 

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

1865 

1866 - `"approximate"`

1867 

1868 - `city: optional string`

1869 

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

1871 

1872 - `country: optional string`

1873 

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

1875 

1876 - `region: optional string`

1877 

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

1879 

1880 - `timezone: optional string`

1881 

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

1883 

1884 - `ApplyPatch object { type }`

1885 

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

1887 

1888 - `type: "apply_patch"`

1889 

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

1891 

1892 - `"apply_patch"`

1893 

1894 - `top_p: optional number`

1895 

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

1897 

1898- `metadata: optional Metadata`

1899 

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

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

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

1903 

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

1905 with a maximum length of 512 characters.

1906 

1907- `name: optional string`

1908 

1909 The name of the run.

1910 

1911### Returns

1912 

1913- `id: string`

1914 

1915 Unique identifier for the evaluation run.

1916 

1917- `created_at: number`

1918 

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

1920 

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

1922 

1923 Information about the run's data source.

1924 

1925 - `CreateEvalJSONLRunDataSource object { source, type }`

1926 

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

1928 

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

1930 

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

1932 

1933 - `EvalJSONLFileContentSource object { content, type }`

1934 

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

1936 

1937 The content of the jsonl file.

1938 

1939 - `item: map[unknown]`

1940 

1941 - `sample: optional map[unknown]`

1942 

1943 - `type: "file_content"`

1944 

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

1946 

1947 - `"file_content"`

1948 

1949 - `EvalJSONLFileIDSource object { id, type }`

1950 

1951 - `id: string`

1952 

1953 The identifier of the file.

1954 

1955 - `type: "file_id"`

1956 

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

1958 

1959 - `"file_id"`

1960 

1961 - `type: "jsonl"`

1962 

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

1964 

1965 - `"jsonl"`

1966 

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

1968 

1969 A CompletionsRunDataSource object describing a model sampling configuration.

1970 

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

1972 

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

1974 

1975 - `EvalJSONLFileContentSource object { content, type }`

1976 

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

1978 

1979 The content of the jsonl file.

1980 

1981 - `item: map[unknown]`

1982 

1983 - `sample: optional map[unknown]`

1984 

1985 - `type: "file_content"`

1986 

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

1988 

1989 - `"file_content"`

1990 

1991 - `EvalJSONLFileIDSource object { id, type }`

1992 

1993 - `id: string`

1994 

1995 The identifier of the file.

1996