cli/resources/chat/subresources/completions/index.md 2026-05-18 22:01 UTC to 2026-05-19 06:34 UTC

1# Completions

2 

3## Create chat completion

4 

5`$ openai chat:completions create`

6 

7**post** `/chat/completions`

8 

9**Starting a new project?** We recommend trying [Responses](https://platform.openai.com/docs/api-reference/responses)

10to take advantage of the latest OpenAI platform features. Compare

11[Chat Completions with Responses](https://platform.openai.com/docs/guides/responses-vs-chat-completions?api-mode=responses).

12 

13 

14Creates a model response for the given chat conversation. Learn more in the

15[text generation](https://platform.openai.com/docs/guides/text-generation), [vision](https://platform.openai.com/docs/guides/vision),

16and [audio](https://platform.openai.com/docs/guides/audio) guides.

17 

18Parameter support can differ depending on the model used to generate the

19response, particularly for newer reasoning models. Parameters that are only

20supported for reasoning models are noted below. For the current state of

21unsupported parameters in reasoning models,

22[refer to the reasoning guide](https://platform.openai.com/docs/guides/reasoning).

23 

24Returns a chat completion object, or a streamed sequence of chat completion

25chunk objects if the request is streamed.

26 

27### Parameters

28 

29- `--message: array of ChatCompletionMessageParam`

30 

31 A list of messages comprising the conversation so far. Depending on the

32 [model](https://platform.openai.com/docs/models) you use, different message types (modalities) are

33 supported, like [text](https://platform.openai.com/docs/guides/text-generation),

34 [images](https://platform.openai.com/docs/guides/vision), and [audio](https://platform.openai.com/docs/guides/audio).

35 

36- `--model: string or ChatModel`

37 

38 Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI

39 offers a wide range of models with different capabilities, performance

40 characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)

41 to browse and compare available models.

42 

43- `--audio: optional object { format, voice }`

44 

45 Parameters for audio output. Required when audio output is requested with

46 `modalities: ["audio"]`. [Learn more](https://platform.openai.com/docs/guides/audio).

47 

48- `--frequency-penalty: optional number`

49 

50 Number between -2.0 and 2.0. Positive values penalize new tokens based on

51 their existing frequency in the text so far, decreasing the model's

52 likelihood to repeat the same line verbatim.

53 

54- `--function-call: optional "none" or "auto" or ChatCompletionFunctionCallOption`

55 

56 Deprecated in favor of `tool_choice`.

57 

58 Controls which (if any) function is called by the model.

59 

60 `none` means the model will not call a function and instead generates a

61 message.

62 

63 `auto` means the model can pick between generating a message or calling a

64 function.

65 

66 Specifying a particular function via `{"name": "my_function"}` forces the

67 model to call that function.

68 

69 `none` is the default when no functions are present. `auto` is the default

70 if functions are present.

71 

72- `--function: optional array of object { name, description, parameters }`

73 

74 Deprecated in favor of `tools`.

75 

76 A list of functions the model may generate JSON inputs for.

77 

78- `--logit-bias: optional map[number]`

79 

80 Modify the likelihood of specified tokens appearing in the completion.

81 

82 Accepts a JSON object that maps tokens (specified by their token ID in the

83 tokenizer) to an associated bias value from -100 to 100. Mathematically,

84 the bias is added to the logits generated by the model prior to sampling.

85 The exact effect will vary per model, but values between -1 and 1 should

86 decrease or increase likelihood of selection; values like -100 or 100

87 should result in a ban or exclusive selection of the relevant token.

88 

89- `--logprobs: optional boolean`

90 

91 Whether to return log probabilities of the output tokens or not. If true,

92 returns the log probabilities of each output token returned in the

93 `content` of `message`.

94 

95- `--max-completion-tokens: optional number`

96 

97 An upper bound for the number of tokens that can be generated for a completion, including visible output tokens and [reasoning tokens](https://platform.openai.com/docs/guides/reasoning).

98 

99- `--max-tokens: optional number`

100 

101 The maximum number of [tokens](/tokenizer) that can be generated in the

102 chat completion. This value can be used to control

103 [costs](https://openai.com/api/pricing/) for text generated via API.

104 

105 This value is now deprecated in favor of `max_completion_tokens`, and is

106 not compatible with [o-series models](https://platform.openai.com/docs/guides/reasoning).

107 

108- `--metadata: optional map[string]`

109 

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

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

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

113 

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

115 with a maximum length of 512 characters.

116 

117- `--modality: optional array of "text" or "audio"`

118 

119 Output types that you would like the model to generate.

120 Most models are capable of generating text, which is the default:

121 

122 `["text"]`

123 

124 The `gpt-4o-audio-preview` model can also be used to

125 [generate audio](https://platform.openai.com/docs/guides/audio). To request that this model generate

126 both text and audio responses, you can use:

127 

128 `["text", "audio"]`

129 

130- `--n: optional number`

131 

132 How many chat completion choices to generate for each input message. Note that you will be charged based on the number of generated tokens across all of the choices. Keep `n` as `1` to minimize costs.

133 

134- `--parallel-tool-calls: optional boolean`

135 

136 Whether to enable [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling) during tool use.

137 

138- `--prediction: optional object { content, type }`

139 

140 Static predicted output content, such as the content of a text file that is

141 being regenerated.

142 

143- `--presence-penalty: optional number`

144 

145 Number between -2.0 and 2.0. Positive values penalize new tokens based on

146 whether they appear in the text so far, increasing the model's likelihood

147 to talk about new topics.

148 

149- `--prompt-cache-key: optional string`

150 

151 Used by OpenAI to cache responses for similar requests to optimize your cache hit rates. Replaces the `user` field. [Learn more](https://platform.openai.com/docs/guides/prompt-caching).

152 

153- `--prompt-cache-retention: optional "in_memory" or "24h"`

154 

155 The retention policy for the prompt cache. Set to `24h` to enable extended prompt caching, which keeps cached prefixes active for longer, up to a maximum of 24 hours. [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).

156 

157- `--reasoning-effort: optional "none" or "minimal" or "low" or 3 more`

158 

159 Constrains effort on reasoning for

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

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

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

163 on reasoning in a response.

164 

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

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

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

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

169 

170- `--response-format: optional ResponseFormatText or ResponseFormatJSONSchema or ResponseFormatJSONObject`

171 

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

173 

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

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

176 schema. Learn more in the [Structured Outputs

177 guide](https://platform.openai.com/docs/guides/structured-outputs).

178 

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

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

181 is preferred for models that support it.

182 

183- `--safety-identifier: optional string`

184 

185 A stable identifier used to help detect users of your application that may be violating OpenAI's usage policies.

186 The IDs should be a string that uniquely identifies each user, with a maximum length of 64 characters. We recommend hashing their username or email address, in order to avoid sending us any identifying information. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).

187 

188- `--seed: optional number`

189 

190 This feature is in Beta.

191 If specified, our system will make a best effort to sample deterministically, such that repeated requests with the same `seed` and parameters should return the same result.

192 Determinism is not guaranteed, and you should refer to the `system_fingerprint` response parameter to monitor changes in the backend.

193 

194- `--service-tier: optional "auto" or "default" or "flex" or 2 more`

195 

196 Specifies the processing type used for serving the request.

197 

198 - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.

199 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.

200 - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.

201 - When not set, the default behavior is 'auto'.

202 

203 When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

204 

205- `--stop: optional string or array of string`

206 

207 Not supported with latest reasoning models `o3` and `o4-mini`.

208 

209 Up to 4 sequences where the API will stop generating further tokens. The

210 returned text will not contain the stop sequence.

211 

212- `--store: optional boolean`

213 

214 Whether or not to store the output of this chat completion request for

215 use in our [model distillation](https://platform.openai.com/docs/guides/distillation) or

216 [evals](https://platform.openai.com/docs/guides/evals) products.

217 

218 Supports text and image inputs. Note: image inputs over 8MB will be dropped.

219 

220- `--stream-options: optional object { include_obfuscation, include_usage }`

221 

222 Options for streaming response. Only set this when you set `stream: true`.

223 

224- `--temperature: optional number`

225 

226 What sampling temperature to use, between 0 and 2. Higher values like 0.8 will make the output more random, while lower values like 0.2 will make it more focused and deterministic.

227 We generally recommend altering this or `top_p` but not both.

228 

229- `--tool-choice: optional "none" or "auto" or "required" or ChatCompletionAllowedToolChoice or ChatCompletionNamedToolChoice or ChatCompletionNamedToolChoiceCustom`

230 

231 Controls which (if any) tool is called by the model.

232 `none` means the model will not call any tool and instead generates a message.

233 `auto` means the model can pick between generating a message or calling one or more tools.

234 `required` means the model must call one or more tools.

235 Specifying a particular tool via `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool.

236 

237 `none` is the default when no tools are present. `auto` is the default if tools are present.

238 

239- `--tool: optional array of ChatCompletionTool`

240 

241 A list of tools the model may call. You can provide either

242 [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools) or

243 [function tools](https://platform.openai.com/docs/guides/function-calling).

244 

245- `--top-logprobs: optional number`

246 

247 An integer between 0 and 20 specifying the maximum number of most likely

248 tokens to return at each token position, each with an associated log

249 probability. In some cases, the number of returned tokens may be fewer than

250 requested.

251 `logprobs` must be set to `true` if this parameter is used.

252 

253- `--top-p: optional number`

254 

255 An alternative to sampling with temperature, called nucleus sampling,

256 where the model considers the results of the tokens with top_p probability

257 mass. So 0.1 means only the tokens comprising the top 10% probability mass

258 are considered.

259 

260 We generally recommend altering this or `temperature` but not both.

261 

262- `--user: optional string`

263 

264 This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use `prompt_cache_key` instead to maintain caching optimizations.

265 A stable identifier for your end-users.

266 Used to boost cache hit rates by better bucketing similar requests and to help OpenAI detect and prevent abuse. [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).

267 

268- `--verbosity: optional "low" or "medium" or "high"`

269 

270 Constrains the verbosity of the model's response. Lower values will result in

271 more concise responses, while higher values will result in more verbose responses.

272 Currently supported values are `low`, `medium`, and `high`.

273 

274- `--web-search-options: optional object { search_context_size, user_location }`

275 

276 This tool searches the web for relevant results to use in a response.

277 Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

278 

279### Returns

280 

281- `chat_completion: object { id, choices, created, 5 more }`

282 

283 Represents a chat completion response returned by model, based on the provided input.

284 

285 - `id: string`

286 

287 A unique identifier for the chat completion.

288 

289 - `choices: array of object { finish_reason, index, logprobs, message }`

290 

291 A list of chat completion choices. Can be more than one if `n` is greater than 1.

292 

293 - `finish_reason: "stop" or "length" or "tool_calls" or 2 more`

294 

295 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,

296 `length` if the maximum number of tokens specified in the request was reached,

297 `content_filter` if content was omitted due to a flag from our content filters,

298 `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.

299 

300 - `"stop"`

301 

302 - `"length"`

303 

304 - `"tool_calls"`

305 

306 - `"content_filter"`

307 

308 - `"function_call"`

309 

310 - `index: number`

311 

312 The index of the choice in the list of choices.

313 

314 - `logprobs: object { content, refusal }`

315 

316 Log probability information for the choice.

317 

318 - `content: array of ChatCompletionTokenLogprob`

319 

320 A list of message content tokens with log probability information.

321 

322 - `token: string`

323 

324 The token.

325 

326 - `bytes: array of number`

327 

328 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

329 

330 - `logprob: number`

331 

332 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

333 

334 - `top_logprobs: array of object { token, bytes, logprob }`

335 

336 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

337 

338 - `token: string`

339 

340 The token.

341 

342 - `bytes: array of number`

343 

344 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

345 

346 - `logprob: number`

347 

348 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

349 

350 - `refusal: array of ChatCompletionTokenLogprob`

351 

352 A list of message refusal tokens with log probability information.

353 

354 - `token: string`

355 

356 The token.

357 

358 - `bytes: array of number`

359 

360 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

361 

362 - `logprob: number`

363 

364 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

365 

366 - `top_logprobs: array of object { token, bytes, logprob }`

367 

368 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

369 

370 - `message: object { content, refusal, role, 4 more }`

371 

372 A chat completion message generated by the model.

373 

374 - `content: string`

375 

376 The contents of the message.

377 

378 - `refusal: string`

379 

380 The refusal message generated by the model.

381 

382 - `role: "assistant"`

383 

384 The role of the author of this message.

385 

386 - `annotations: optional array of object { type, url_citation }`

387 

388 Annotations for the message, when applicable, as when using the

389 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

390 

391 - `type: "url_citation"`

392 

393 The type of the URL citation. Always `url_citation`.

394 

395 - `url_citation: object { end_index, start_index, title, url }`

396 

397 A URL citation when using web search.

398 

399 - `end_index: number`

400 

401 The index of the last character of the URL citation in the message.

402 

403 - `start_index: number`

404 

405 The index of the first character of the URL citation in the message.

406 

407 - `title: string`

408 

409 The title of the web resource.

410 

411 - `url: string`

412 

413 The URL of the web resource.

414 

415 - `audio: optional object { id, data, expires_at, transcript }`

416 

417 If the audio output modality is requested, this object contains data

418 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

419 

420 - `id: string`

421 

422 Unique identifier for this audio response.

423 

424 - `data: string`

425 

426 Base64 encoded audio bytes generated by the model, in the format

427 specified in the request.

428 

429 - `expires_at: number`

430 

431 The Unix timestamp (in seconds) for when this audio response will

432 no longer be accessible on the server for use in multi-turn

433 conversations.

434 

435 - `transcript: string`

436 

437 Transcript of the audio generated by the model.

438 

439 - `function_call: optional object { arguments, name }`

440 

441 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.

442 

443 - `arguments: string`

444 

445 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

446 

447 - `name: string`

448 

449 The name of the function to call.

450 

451 - `tool_calls: optional array of ChatCompletionMessageToolCall`

452 

453 The tool calls generated by the model, such as function calls.

454 

455 - `chat_completion_message_function_tool_call: object { id, function, type }`

456 

457 A call to a function tool created by the model.

458 

459 - `id: string`

460 

461 The ID of the tool call.

462 

463 - `function: object { arguments, name }`

464 

465 The function that the model called.

466 

467 - `arguments: string`

468 

469 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

470 

471 - `name: string`

472 

473 The name of the function to call.

474 

475 - `type: "function"`

476 

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

478 

479 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

480 

481 A call to a custom tool created by the model.

482 

483 - `id: string`

484 

485 The ID of the tool call.

486 

487 - `custom: object { input, name }`

488 

489 The custom tool that the model called.

490 

491 - `input: string`

492 

493 The input for the custom tool call generated by the model.

494 

495 - `name: string`

496 

497 The name of the custom tool to call.

498 

499 - `type: "custom"`

500 

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

502 

503 - `created: number`

504 

505 The Unix timestamp (in seconds) of when the chat completion was created.

506 

507 - `model: string`

508 

509 The model used for the chat completion.

510 

511 - `object: "chat.completion"`

512 

513 The object type, which is always `chat.completion`.

514 

515 - `service_tier: optional "auto" or "default" or "flex" or 2 more`

516 

517 Specifies the processing type used for serving the request.

518 

519 - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.

520 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.

521 - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.

522 - When not set, the default behavior is 'auto'.

523 

524 When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

525 

526 - `"auto"`

527 

528 - `"default"`

529 

530 - `"flex"`

531 

532 - `"scale"`

533 

534 - `"priority"`

535 

536 - `system_fingerprint: optional string`

537 

538 This fingerprint represents the backend configuration that the model runs with.

539 

540 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.

541 

542 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

543 

544 Usage statistics for the completion request.

545 

546 - `completion_tokens: number`

547 

548 Number of tokens in the generated completion.

549 

550 - `prompt_tokens: number`

551 

552 Number of tokens in the prompt.

553 

554 - `total_tokens: number`

555 

556 Total number of tokens used in the request (prompt + completion).

557 

558 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }`

559 

560 Breakdown of tokens used in a completion.

561 

562 - `accepted_prediction_tokens: optional number`

563 

564 When using Predicted Outputs, the number of tokens in the

565 prediction that appeared in the completion.

566 

567 - `audio_tokens: optional number`

568 

569 Audio input tokens generated by the model.

570 

571 - `reasoning_tokens: optional number`

572 

573 Tokens generated by the model for reasoning.

574 

575 - `rejected_prediction_tokens: optional number`

576 

577 When using Predicted Outputs, the number of tokens in the

578 prediction that did not appear in the completion. However, like

579 reasoning tokens, these tokens are still counted in the total

580 completion tokens for purposes of billing, output, and context window

581 limits.

582 

583 - `prompt_tokens_details: optional object { audio_tokens, cached_tokens }`

584 

585 Breakdown of tokens used in the prompt.

586 

587 - `audio_tokens: optional number`

588 

589 Audio input tokens present in the prompt.

590 

591 - `cached_tokens: optional number`

592 

593 Cached tokens present in the prompt.

594 

595### Example

596 

597```cli

598openai chat:completions create \

599 --api-key 'My API Key' \

600 --message '{content: string, role: developer}' \

601 --model gpt-5.4

602```

603 

604#### Response

605 

606```json

607{

608 "id": "id",

609 "choices": [

610 {

611 "finish_reason": "stop",

612 "index": 0,

613 "logprobs": {

614 "content": [

615 {

616 "token": "token",

617 "bytes": [

618 0

619 ],

620 "logprob": 0,

621 "top_logprobs": [

622 {

623 "token": "token",

624 "bytes": [

625 0

626 ],

627 "logprob": 0

628 }

629 ]

630 }

631 ],

632 "refusal": [

633 {

634 "token": "token",

635 "bytes": [

636 0

637 ],

638 "logprob": 0,

639 "top_logprobs": [

640 {

641 "token": "token",

642 "bytes": [

643 0

644 ],

645 "logprob": 0

646 }

647 ]

648 }

649 ]

650 },

651 "message": {

652 "content": "content",

653 "refusal": "refusal",

654 "role": "assistant",

655 "annotations": [

656 {

657 "type": "url_citation",

658 "url_citation": {

659 "end_index": 0,

660 "start_index": 0,

661 "title": "title",

662 "url": "https://example.com"

663 }

664 }

665 ],

666 "audio": {

667 "id": "id",

668 "data": "data",

669 "expires_at": 0,

670 "transcript": "transcript"

671 },

672 "function_call": {

673 "arguments": "arguments",

674 "name": "name"

675 },

676 "tool_calls": [

677 {

678 "id": "id",

679 "function": {

680 "arguments": "arguments",

681 "name": "name"

682 },

683 "type": "function"

684 }

685 ]

686 }

687 }

688 ],

689 "created": 0,

690 "model": "model",

691 "object": "chat.completion",

692 "service_tier": "auto",

693 "system_fingerprint": "system_fingerprint",

694 "usage": {

695 "completion_tokens": 0,

696 "prompt_tokens": 0,

697 "total_tokens": 0,

698 "completion_tokens_details": {

699 "accepted_prediction_tokens": 0,

700 "audio_tokens": 0,

701 "reasoning_tokens": 0,

702 "rejected_prediction_tokens": 0

703 },

704 "prompt_tokens_details": {

705 "audio_tokens": 0,

706 "cached_tokens": 0

707 }

708 }

709}

710```

711 

712## List Chat Completions

713 

714`$ openai chat:completions list`

715 

716**get** `/chat/completions`

717 

718List stored Chat Completions. Only Chat Completions that have been stored

719with the `store` parameter set to `true` will be returned.

720 

721### Parameters

722 

723- `--after: optional string`

724 

725 Identifier for the last chat completion from the previous pagination request.

726 

727- `--limit: optional number`

728 

729 Number of Chat Completions to retrieve.

730 

731- `--metadata: optional map[string]`

732 

733 A list of metadata keys to filter the Chat Completions by. Example:

734 

735 `metadata[key1]=value1&metadata[key2]=value2`

736 

737- `--model: optional string`

738 

739 The model used to generate the Chat Completions.

740 

741- `--order: optional "asc" or "desc"`

742 

743 Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`.

744 

745### Returns

746 

747- `ChatCompletionList: object { data, first_id, has_more, 2 more }`

748 

749 An object representing a list of Chat Completions.

750 

751 - `data: array of ChatCompletion`

752 

753 An array of chat completion objects.

754 

755 - `id: string`

756 

757 A unique identifier for the chat completion.

758 

759 - `choices: array of object { finish_reason, index, logprobs, message }`

760 

761 A list of chat completion choices. Can be more than one if `n` is greater than 1.

762 

763 - `finish_reason: "stop" or "length" or "tool_calls" or 2 more`

764 

765 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,

766 `length` if the maximum number of tokens specified in the request was reached,

767 `content_filter` if content was omitted due to a flag from our content filters,

768 `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.

769 

770 - `"stop"`

771 

772 - `"length"`

773 

774 - `"tool_calls"`

775 

776 - `"content_filter"`

777 

778 - `"function_call"`

779 

780 - `index: number`

781 

782 The index of the choice in the list of choices.

783 

784 - `logprobs: object { content, refusal }`

785 

786 Log probability information for the choice.

787 

788 - `content: array of ChatCompletionTokenLogprob`

789 

790 A list of message content tokens with log probability information.

791 

792 - `token: string`

793 

794 The token.

795 

796 - `bytes: array of number`

797 

798 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

799 

800 - `logprob: number`

801 

802 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

803 

804 - `top_logprobs: array of object { token, bytes, logprob }`

805 

806 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

807 

808 - `token: string`

809 

810 The token.

811 

812 - `bytes: array of number`

813 

814 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

815 

816 - `logprob: number`

817 

818 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

819 

820 - `refusal: array of ChatCompletionTokenLogprob`

821 

822 A list of message refusal tokens with log probability information.

823 

824 - `token: string`

825 

826 The token.

827 

828 - `bytes: array of number`

829 

830 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

831 

832 - `logprob: number`

833 

834 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

835 

836 - `top_logprobs: array of object { token, bytes, logprob }`

837 

838 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

839 

840 - `message: object { content, refusal, role, 4 more }`

841 

842 A chat completion message generated by the model.

843 

844 - `content: string`

845 

846 The contents of the message.

847 

848 - `refusal: string`

849 

850 The refusal message generated by the model.

851 

852 - `role: "assistant"`

853 

854 The role of the author of this message.

855 

856 - `annotations: optional array of object { type, url_citation }`

857 

858 Annotations for the message, when applicable, as when using the

859 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

860 

861 - `type: "url_citation"`

862 

863 The type of the URL citation. Always `url_citation`.

864 

865 - `url_citation: object { end_index, start_index, title, url }`

866 

867 A URL citation when using web search.

868 

869 - `end_index: number`

870 

871 The index of the last character of the URL citation in the message.

872 

873 - `start_index: number`

874 

875 The index of the first character of the URL citation in the message.

876 

877 - `title: string`

878 

879 The title of the web resource.

880 

881 - `url: string`

882 

883 The URL of the web resource.

884 

885 - `audio: optional object { id, data, expires_at, transcript }`

886 

887 If the audio output modality is requested, this object contains data

888 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

889 

890 - `id: string`

891 

892 Unique identifier for this audio response.

893 

894 - `data: string`

895 

896 Base64 encoded audio bytes generated by the model, in the format

897 specified in the request.

898 

899 - `expires_at: number`

900 

901 The Unix timestamp (in seconds) for when this audio response will

902 no longer be accessible on the server for use in multi-turn

903 conversations.

904 

905 - `transcript: string`

906 

907 Transcript of the audio generated by the model.

908 

909 - `function_call: optional object { arguments, name }`

910 

911 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.

912 

913 - `arguments: string`

914 

915 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

916 

917 - `name: string`

918 

919 The name of the function to call.

920 

921 - `tool_calls: optional array of ChatCompletionMessageToolCall`

922 

923 The tool calls generated by the model, such as function calls.

924 

925 - `chat_completion_message_function_tool_call: object { id, function, type }`

926 

927 A call to a function tool created by the model.

928 

929 - `id: string`

930 

931 The ID of the tool call.

932 

933 - `function: object { arguments, name }`

934 

935 The function that the model called.

936 

937 - `arguments: string`

938 

939 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

940 

941 - `name: string`

942 

943 The name of the function to call.

944 

945 - `type: "function"`

946 

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

948 

949 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

950 

951 A call to a custom tool created by the model.

952 

953 - `id: string`

954 

955 The ID of the tool call.

956 

957 - `custom: object { input, name }`

958 

959 The custom tool that the model called.

960 

961 - `input: string`

962 

963 The input for the custom tool call generated by the model.

964 

965 - `name: string`

966 

967 The name of the custom tool to call.

968 

969 - `type: "custom"`

970 

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

972 

973 - `created: number`

974 

975 The Unix timestamp (in seconds) of when the chat completion was created.

976 

977 - `model: string`

978 

979 The model used for the chat completion.

980 

981 - `object: "chat.completion"`

982 

983 The object type, which is always `chat.completion`.

984 

985 - `service_tier: optional "auto" or "default" or "flex" or 2 more`

986 

987 Specifies the processing type used for serving the request.

988 

989 - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.

990 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.

991 - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.

992 - When not set, the default behavior is 'auto'.

993 

994 When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

995 

996 - `"auto"`

997 

998 - `"default"`

999 

1000 - `"flex"`

1001 

1002 - `"scale"`

1003 

1004 - `"priority"`

1005 

1006 - `system_fingerprint: optional string`

1007 

1008 This fingerprint represents the backend configuration that the model runs with.

1009 

1010 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.

1011 

1012 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

1013 

1014 Usage statistics for the completion request.

1015 

1016 - `completion_tokens: number`

1017 

1018 Number of tokens in the generated completion.

1019 

1020 - `prompt_tokens: number`

1021 

1022 Number of tokens in the prompt.

1023 

1024 - `total_tokens: number`

1025 

1026 Total number of tokens used in the request (prompt + completion).

1027 

1028 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }`

1029 

1030 Breakdown of tokens used in a completion.

1031 

1032 - `accepted_prediction_tokens: optional number`

1033 

1034 When using Predicted Outputs, the number of tokens in the

1035 prediction that appeared in the completion.

1036 

1037 - `audio_tokens: optional number`

1038 

1039 Audio input tokens generated by the model.

1040 

1041 - `reasoning_tokens: optional number`

1042 

1043 Tokens generated by the model for reasoning.

1044 

1045 - `rejected_prediction_tokens: optional number`

1046 

1047 When using Predicted Outputs, the number of tokens in the

1048 prediction that did not appear in the completion. However, like

1049 reasoning tokens, these tokens are still counted in the total

1050 completion tokens for purposes of billing, output, and context window

1051 limits.

1052 

1053 - `prompt_tokens_details: optional object { audio_tokens, cached_tokens }`

1054 

1055 Breakdown of tokens used in the prompt.

1056 

1057 - `audio_tokens: optional number`

1058 

1059 Audio input tokens present in the prompt.

1060 

1061 - `cached_tokens: optional number`

1062 

1063 Cached tokens present in the prompt.

1064 

1065 - `first_id: string`

1066 

1067 The identifier of the first chat completion in the data array.

1068 

1069 - `has_more: boolean`

1070 

1071 Indicates whether there are more Chat Completions available.

1072 

1073 - `last_id: string`

1074 

1075 The identifier of the last chat completion in the data array.

1076 

1077 - `object: "list"`

1078 

1079 The type of this object. It is always set to "list".

1080 

1081### Example

1082 

1083```cli

1084openai chat:completions list \

1085 --api-key 'My API Key'

1086```

1087 

1088#### Response

1089 

1090```json

1091{

1092 "data": [

1093 {

1094 "id": "id",

1095 "choices": [

1096 {

1097 "finish_reason": "stop",

1098 "index": 0,

1099 "logprobs": {

1100 "content": [

1101 {

1102 "token": "token",

1103 "bytes": [

1104 0

1105 ],

1106 "logprob": 0,

1107 "top_logprobs": [

1108 {

1109 "token": "token",

1110 "bytes": [

1111 0

1112 ],

1113 "logprob": 0

1114 }

1115 ]

1116 }

1117 ],

1118 "refusal": [

1119 {

1120 "token": "token",

1121 "bytes": [

1122 0

1123 ],

1124 "logprob": 0,

1125 "top_logprobs": [

1126 {

1127 "token": "token",

1128 "bytes": [

1129 0

1130 ],

1131 "logprob": 0

1132 }

1133 ]

1134 }

1135 ]

1136 },

1137 "message": {

1138 "content": "content",

1139 "refusal": "refusal",

1140 "role": "assistant",

1141 "annotations": [

1142 {

1143 "type": "url_citation",

1144 "url_citation": {

1145 "end_index": 0,

1146 "start_index": 0,

1147 "title": "title",

1148 "url": "https://example.com"

1149 }

1150 }

1151 ],

1152 "audio": {

1153 "id": "id",

1154 "data": "data",

1155 "expires_at": 0,

1156 "transcript": "transcript"

1157 },

1158 "function_call": {

1159 "arguments": "arguments",

1160 "name": "name"

1161 },

1162 "tool_calls": [

1163 {

1164 "id": "id",

1165 "function": {

1166 "arguments": "arguments",

1167 "name": "name"

1168 },

1169 "type": "function"

1170 }

1171 ]

1172 }

1173 }

1174 ],

1175 "created": 0,

1176 "model": "model",

1177 "object": "chat.completion",

1178 "service_tier": "auto",

1179 "system_fingerprint": "system_fingerprint",

1180 "usage": {

1181 "completion_tokens": 0,

1182 "prompt_tokens": 0,

1183 "total_tokens": 0,

1184 "completion_tokens_details": {

1185 "accepted_prediction_tokens": 0,

1186 "audio_tokens": 0,

1187 "reasoning_tokens": 0,

1188 "rejected_prediction_tokens": 0

1189 },

1190 "prompt_tokens_details": {

1191 "audio_tokens": 0,

1192 "cached_tokens": 0

1193 }

1194 }

1195 }

1196 ],

1197 "first_id": "first_id",

1198 "has_more": true,

1199 "last_id": "last_id",

1200 "object": "list"

1201}

1202```

1203 

1204## Get chat completion

1205 

1206`$ openai chat:completions retrieve`

1207 

1208**get** `/chat/completions/{completion_id}`

1209 

1210Get a stored chat completion. Only Chat Completions that have been created

1211with the `store` parameter set to `true` will be returned.

1212 

1213### Parameters

1214 

1215- `--completion-id: string`

1216 

1217 The ID of the chat completion to retrieve.

1218 

1219### Returns

1220 

1221- `chat_completion: object { id, choices, created, 5 more }`

1222 

1223 Represents a chat completion response returned by model, based on the provided input.

1224 

1225 - `id: string`

1226 

1227 A unique identifier for the chat completion.

1228 

1229 - `choices: array of object { finish_reason, index, logprobs, message }`

1230 

1231 A list of chat completion choices. Can be more than one if `n` is greater than 1.

1232 

1233 - `finish_reason: "stop" or "length" or "tool_calls" or 2 more`

1234 

1235 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,

1236 `length` if the maximum number of tokens specified in the request was reached,

1237 `content_filter` if content was omitted due to a flag from our content filters,

1238 `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.

1239 

1240 - `"stop"`

1241 

1242 - `"length"`

1243 

1244 - `"tool_calls"`

1245 

1246 - `"content_filter"`

1247 

1248 - `"function_call"`

1249 

1250 - `index: number`

1251 

1252 The index of the choice in the list of choices.

1253 

1254 - `logprobs: object { content, refusal }`

1255 

1256 Log probability information for the choice.

1257 

1258 - `content: array of ChatCompletionTokenLogprob`

1259 

1260 A list of message content tokens with log probability information.

1261 

1262 - `token: string`

1263 

1264 The token.

1265 

1266 - `bytes: array of number`

1267 

1268 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1269 

1270 - `logprob: number`

1271 

1272 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1273 

1274 - `top_logprobs: array of object { token, bytes, logprob }`

1275 

1276 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

1277 

1278 - `token: string`

1279 

1280 The token.

1281 

1282 - `bytes: array of number`

1283 

1284 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1285 

1286 - `logprob: number`

1287 

1288 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1289 

1290 - `refusal: array of ChatCompletionTokenLogprob`

1291 

1292 A list of message refusal tokens with log probability information.

1293 

1294 - `token: string`

1295 

1296 The token.

1297 

1298 - `bytes: array of number`

1299 

1300 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1301 

1302 - `logprob: number`

1303 

1304 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1305 

1306 - `top_logprobs: array of object { token, bytes, logprob }`

1307 

1308 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

1309 

1310 - `message: object { content, refusal, role, 4 more }`

1311 

1312 A chat completion message generated by the model.

1313 

1314 - `content: string`

1315 

1316 The contents of the message.

1317 

1318 - `refusal: string`

1319 

1320 The refusal message generated by the model.

1321 

1322 - `role: "assistant"`

1323 

1324 The role of the author of this message.

1325 

1326 - `annotations: optional array of object { type, url_citation }`

1327 

1328 Annotations for the message, when applicable, as when using the

1329 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

1330 

1331 - `type: "url_citation"`

1332 

1333 The type of the URL citation. Always `url_citation`.

1334 

1335 - `url_citation: object { end_index, start_index, title, url }`

1336 

1337 A URL citation when using web search.

1338 

1339 - `end_index: number`

1340 

1341 The index of the last character of the URL citation in the message.

1342 

1343 - `start_index: number`

1344 

1345 The index of the first character of the URL citation in the message.

1346 

1347 - `title: string`

1348 

1349 The title of the web resource.

1350 

1351 - `url: string`

1352 

1353 The URL of the web resource.

1354 

1355 - `audio: optional object { id, data, expires_at, transcript }`

1356 

1357 If the audio output modality is requested, this object contains data

1358 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

1359 

1360 - `id: string`

1361 

1362 Unique identifier for this audio response.

1363 

1364 - `data: string`

1365 

1366 Base64 encoded audio bytes generated by the model, in the format

1367 specified in the request.

1368 

1369 - `expires_at: number`

1370 

1371 The Unix timestamp (in seconds) for when this audio response will

1372 no longer be accessible on the server for use in multi-turn

1373 conversations.

1374 

1375 - `transcript: string`

1376 

1377 Transcript of the audio generated by the model.

1378 

1379 - `function_call: optional object { arguments, name }`

1380 

1381 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.

1382 

1383 - `arguments: string`

1384 

1385 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

1386 

1387 - `name: string`

1388 

1389 The name of the function to call.

1390 

1391 - `tool_calls: optional array of ChatCompletionMessageToolCall`

1392 

1393 The tool calls generated by the model, such as function calls.

1394 

1395 - `chat_completion_message_function_tool_call: object { id, function, type }`

1396 

1397 A call to a function tool created by the model.

1398 

1399 - `id: string`

1400 

1401 The ID of the tool call.

1402 

1403 - `function: object { arguments, name }`

1404 

1405 The function that the model called.

1406 

1407 - `arguments: string`

1408 

1409 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

1410 

1411 - `name: string`

1412 

1413 The name of the function to call.

1414 

1415 - `type: "function"`

1416 

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

1418 

1419 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

1420 

1421 A call to a custom tool created by the model.

1422 

1423 - `id: string`

1424 

1425 The ID of the tool call.

1426 

1427 - `custom: object { input, name }`

1428 

1429 The custom tool that the model called.

1430 

1431 - `input: string`

1432 

1433 The input for the custom tool call generated by the model.

1434 

1435 - `name: string`

1436 

1437 The name of the custom tool to call.

1438 

1439 - `type: "custom"`

1440 

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

1442 

1443 - `created: number`

1444 

1445 The Unix timestamp (in seconds) of when the chat completion was created.

1446 

1447 - `model: string`

1448 

1449 The model used for the chat completion.

1450 

1451 - `object: "chat.completion"`

1452 

1453 The object type, which is always `chat.completion`.

1454 

1455 - `service_tier: optional "auto" or "default" or "flex" or 2 more`

1456 

1457 Specifies the processing type used for serving the request.

1458 

1459 - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.

1460 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.

1461 - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.

1462 - When not set, the default behavior is 'auto'.

1463 

1464 When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

1465 

1466 - `"auto"`

1467 

1468 - `"default"`

1469 

1470 - `"flex"`

1471 

1472 - `"scale"`

1473 

1474 - `"priority"`

1475 

1476 - `system_fingerprint: optional string`

1477 

1478 This fingerprint represents the backend configuration that the model runs with.

1479 

1480 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.

1481 

1482 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

1483 

1484 Usage statistics for the completion request.

1485 

1486 - `completion_tokens: number`

1487 

1488 Number of tokens in the generated completion.

1489 

1490 - `prompt_tokens: number`

1491 

1492 Number of tokens in the prompt.

1493 

1494 - `total_tokens: number`

1495 

1496 Total number of tokens used in the request (prompt + completion).

1497 

1498 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }`

1499 

1500 Breakdown of tokens used in a completion.

1501 

1502 - `accepted_prediction_tokens: optional number`

1503 

1504 When using Predicted Outputs, the number of tokens in the

1505 prediction that appeared in the completion.

1506 

1507 - `audio_tokens: optional number`

1508 

1509 Audio input tokens generated by the model.

1510 

1511 - `reasoning_tokens: optional number`

1512 

1513 Tokens generated by the model for reasoning.

1514 

1515 - `rejected_prediction_tokens: optional number`

1516 

1517 When using Predicted Outputs, the number of tokens in the

1518 prediction that did not appear in the completion. However, like

1519 reasoning tokens, these tokens are still counted in the total

1520 completion tokens for purposes of billing, output, and context window

1521 limits.

1522 

1523 - `prompt_tokens_details: optional object { audio_tokens, cached_tokens }`

1524 

1525 Breakdown of tokens used in the prompt.

1526 

1527 - `audio_tokens: optional number`

1528 

1529 Audio input tokens present in the prompt.

1530 

1531 - `cached_tokens: optional number`

1532 

1533 Cached tokens present in the prompt.

1534 

1535### Example

1536 

1537```cli

1538openai chat:completions retrieve \

1539 --api-key 'My API Key' \

1540 --completion-id completion_id

1541```

1542 

1543#### Response

1544 

1545```json

1546{

1547 "id": "id",

1548 "choices": [

1549 {

1550 "finish_reason": "stop",

1551 "index": 0,

1552 "logprobs": {

1553 "content": [

1554 {

1555 "token": "token",

1556 "bytes": [

1557 0

1558 ],

1559 "logprob": 0,

1560 "top_logprobs": [

1561 {

1562 "token": "token",

1563 "bytes": [

1564 0

1565 ],

1566 "logprob": 0

1567 }

1568 ]

1569 }

1570 ],

1571 "refusal": [

1572 {

1573 "token": "token",

1574 "bytes": [

1575 0

1576 ],

1577 "logprob": 0,

1578 "top_logprobs": [

1579 {

1580 "token": "token",

1581 "bytes": [

1582 0

1583 ],

1584 "logprob": 0

1585 }

1586 ]

1587 }

1588 ]

1589 },

1590 "message": {

1591 "content": "content",

1592 "refusal": "refusal",

1593 "role": "assistant",

1594 "annotations": [

1595 {

1596 "type": "url_citation",

1597 "url_citation": {

1598 "end_index": 0,

1599 "start_index": 0,

1600 "title": "title",

1601 "url": "https://example.com"

1602 }

1603 }

1604 ],

1605 "audio": {

1606 "id": "id",

1607 "data": "data",

1608 "expires_at": 0,

1609 "transcript": "transcript"

1610 },

1611 "function_call": {

1612 "arguments": "arguments",

1613 "name": "name"

1614 },

1615 "tool_calls": [

1616 {

1617 "id": "id",

1618 "function": {

1619 "arguments": "arguments",

1620 "name": "name"

1621 },

1622 "type": "function"

1623 }

1624 ]

1625 }

1626 }

1627 ],

1628 "created": 0,

1629 "model": "model",

1630 "object": "chat.completion",

1631 "service_tier": "auto",

1632 "system_fingerprint": "system_fingerprint",

1633 "usage": {

1634 "completion_tokens": 0,

1635 "prompt_tokens": 0,

1636 "total_tokens": 0,

1637 "completion_tokens_details": {

1638 "accepted_prediction_tokens": 0,

1639 "audio_tokens": 0,

1640 "reasoning_tokens": 0,

1641 "rejected_prediction_tokens": 0

1642 },

1643 "prompt_tokens_details": {

1644 "audio_tokens": 0,

1645 "cached_tokens": 0

1646 }

1647 }

1648}

1649```

1650 

1651## Update chat completion

1652 

1653`$ openai chat:completions update`

1654 

1655**post** `/chat/completions/{completion_id}`

1656 

1657Modify a stored chat completion. Only Chat Completions that have been

1658created with the `store` parameter set to `true` can be modified. Currently,

1659the only supported modification is to update the `metadata` field.

1660 

1661### Parameters

1662 

1663- `--completion-id: string`

1664 

1665 The ID of the chat completion to update.

1666 

1667- `--metadata: map[string]`

1668 

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

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

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

1672 

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

1674 with a maximum length of 512 characters.

1675 

1676### Returns

1677 

1678- `chat_completion: object { id, choices, created, 5 more }`

1679 

1680 Represents a chat completion response returned by model, based on the provided input.

1681 

1682 - `id: string`

1683 

1684 A unique identifier for the chat completion.

1685 

1686 - `choices: array of object { finish_reason, index, logprobs, message }`

1687 

1688 A list of chat completion choices. Can be more than one if `n` is greater than 1.

1689 

1690 - `finish_reason: "stop" or "length" or "tool_calls" or 2 more`

1691 

1692 The reason the model stopped generating tokens. This will be `stop` if the model hit a natural stop point or a provided stop sequence,

1693 `length` if the maximum number of tokens specified in the request was reached,

1694 `content_filter` if content was omitted due to a flag from our content filters,

1695 `tool_calls` if the model called a tool, or `function_call` (deprecated) if the model called a function.

1696 

1697 - `"stop"`

1698 

1699 - `"length"`

1700 

1701 - `"tool_calls"`

1702 

1703 - `"content_filter"`

1704 

1705 - `"function_call"`

1706 

1707 - `index: number`

1708 

1709 The index of the choice in the list of choices.

1710 

1711 - `logprobs: object { content, refusal }`

1712 

1713 Log probability information for the choice.

1714 

1715 - `content: array of ChatCompletionTokenLogprob`

1716 

1717 A list of message content tokens with log probability information.

1718 

1719 - `token: string`

1720 

1721 The token.

1722 

1723 - `bytes: array of number`

1724 

1725 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1726 

1727 - `logprob: number`

1728 

1729 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1730 

1731 - `top_logprobs: array of object { token, bytes, logprob }`

1732 

1733 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

1734 

1735 - `token: string`

1736 

1737 The token.

1738 

1739 - `bytes: array of number`

1740 

1741 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1742 

1743 - `logprob: number`

1744 

1745 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1746 

1747 - `refusal: array of ChatCompletionTokenLogprob`

1748 

1749 A list of message refusal tokens with log probability information.

1750 

1751 - `token: string`

1752 

1753 The token.

1754 

1755 - `bytes: array of number`

1756 

1757 A list of integers representing the UTF-8 bytes representation of the token. Useful in instances where characters are represented by multiple tokens and their byte representations must be combined to generate the correct text representation. Can be `null` if there is no bytes representation for the token.

1758 

1759 - `logprob: number`

1760 

1761 The log probability of this token, if it is within the top 20 most likely tokens. Otherwise, the value `-9999.0` is used to signify that the token is very unlikely.

1762 

1763 - `top_logprobs: array of object { token, bytes, logprob }`

1764 

1765 List of the most likely tokens and their log probability, at this token position. The number of entries may be fewer than the requested `top_logprobs`.

1766 

1767 - `message: object { content, refusal, role, 4 more }`

1768 

1769 A chat completion message generated by the model.

1770 

1771 - `content: string`

1772 

1773 The contents of the message.

1774 

1775 - `refusal: string`

1776 

1777 The refusal message generated by the model.

1778 

1779 - `role: "assistant"`

1780 

1781 The role of the author of this message.

1782 

1783 - `annotations: optional array of object { type, url_citation }`

1784 

1785 Annotations for the message, when applicable, as when using the

1786 [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).

1787 

1788 - `type: "url_citation"`

1789 

1790 The type of the URL citation. Always `url_citation`.

1791 

1792 - `url_citation: object { end_index, start_index, title, url }`

1793 

1794 A URL citation when using web search.

1795 

1796 - `end_index: number`

1797 

1798 The index of the last character of the URL citation in the message.

1799 

1800 - `start_index: number`

1801 

1802 The index of the first character of the URL citation in the message.

1803 

1804 - `title: string`

1805 

1806 The title of the web resource.

1807 

1808 - `url: string`

1809 

1810 The URL of the web resource.

1811 

1812 - `audio: optional object { id, data, expires_at, transcript }`

1813 

1814 If the audio output modality is requested, this object contains data

1815 about the audio response from the model. [Learn more](https://platform.openai.com/docs/guides/audio).

1816 

1817 - `id: string`

1818 

1819 Unique identifier for this audio response.

1820 

1821 - `data: string`

1822 

1823 Base64 encoded audio bytes generated by the model, in the format

1824 specified in the request.

1825 

1826 - `expires_at: number`

1827 

1828 The Unix timestamp (in seconds) for when this audio response will

1829 no longer be accessible on the server for use in multi-turn

1830 conversations.

1831 

1832 - `transcript: string`

1833 

1834 Transcript of the audio generated by the model.

1835 

1836 - `function_call: optional object { arguments, name }`

1837 

1838 Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model.

1839 

1840 - `arguments: string`

1841 

1842 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

1843 

1844 - `name: string`

1845 

1846 The name of the function to call.

1847 

1848 - `tool_calls: optional array of ChatCompletionMessageToolCall`

1849 

1850 The tool calls generated by the model, such as function calls.

1851 

1852 - `chat_completion_message_function_tool_call: object { id, function, type }`

1853 

1854 A call to a function tool created by the model.

1855 

1856 - `id: string`

1857 

1858 The ID of the tool call.

1859 

1860 - `function: object { arguments, name }`

1861 

1862 The function that the model called.

1863 

1864 - `arguments: string`

1865 

1866 The arguments to call the function with, as generated by the model in JSON format. Note that the model does not always generate valid JSON, and may hallucinate parameters not defined by your function schema. Validate the arguments in your code before calling your function.

1867 

1868 - `name: string`

1869 

1870 The name of the function to call.

1871 

1872 - `type: "function"`

1873 

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

1875 

1876 - `chat_completion_message_custom_tool_call: object { id, custom, type }`

1877 

1878 A call to a custom tool created by the model.

1879 

1880 - `id: string`

1881 

1882 The ID of the tool call.

1883 

1884 - `custom: object { input, name }`

1885 

1886 The custom tool that the model called.

1887 

1888 - `input: string`

1889 

1890 The input for the custom tool call generated by the model.

1891 

1892 - `name: string`

1893 

1894 The name of the custom tool to call.

1895 

1896 - `type: "custom"`

1897 

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

1899 

1900 - `created: number`

1901 

1902 The Unix timestamp (in seconds) of when the chat completion was created.

1903 

1904 - `model: string`

1905 

1906 The model used for the chat completion.

1907 

1908 - `object: "chat.completion"`

1909 

1910 The object type, which is always `chat.completion`.

1911 

1912 - `service_tier: optional "auto" or "default" or "flex" or 2 more`

1913 

1914 Specifies the processing type used for serving the request.

1915 

1916 - If set to 'auto', then the request will be processed with the service tier configured in the Project settings. Unless otherwise configured, the Project will use 'default'.

1917 - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.

1918 - If set to '[flex](https://platform.openai.com/docs/guides/flex-processing)' or '[priority](https://openai.com/api-priority-processing/)', then the request will be processed with the corresponding service tier.

1919 - When not set, the default behavior is 'auto'.

1920 

1921 When the `service_tier` parameter is set, the response body will include the `service_tier` value based on the processing mode actually used to serve the request. This response value may be different from the value set in the parameter.

1922 

1923 - `"auto"`

1924 

1925 - `"default"`

1926 

1927 - `"flex"`

1928 

1929 - `"scale"`

1930 

1931 - `"priority"`

1932 

1933 - `system_fingerprint: optional string`

1934 

1935 This fingerprint represents the backend configuration that the model runs with.

1936 

1937 Can be used in conjunction with the `seed` request parameter to understand when backend changes have been made that might impact determinism.

1938 

1939 - `usage: optional object { completion_tokens, prompt_tokens, total_tokens, 2 more }`

1940 

1941 Usage statistics for the completion request.

1942 

1943 - `completion_tokens: number`

1944 

1945 Number of tokens in the generated completion.

1946 

1947 - `prompt_tokens: number`

1948 

1949 Number of tokens in the prompt.

1950 

1951 - `total_tokens: number`

1952 

1953 Total number of tokens used in the request (prompt + completion).

1954 

1955 - `completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }`

1956 

1957 Breakdown of tokens used in a completion.

1958 

1959 - `accepted_prediction_tokens: optional number`

1960 

1961 When using Predicted Outputs, the number of tokens in the

1962 prediction that appeared in the completion.

1963 

1964 - `audio_tokens: optional number`

1965 

1966 Audio input tokens generated by the model.

1967 

1968 - `reasoning_tokens: optional number`

1969 

1970 Tokens generated by the model for reasoning.

1971 

1972 - `rejected_prediction_tokens: optional number`

1973 

1974 When using Predicted Outputs, the number of tokens in the

1975 prediction that did not appear in the completion. However, like

1976 reasoning tokens, these tokens are still counted in the total

1977 completion tokens for purposes of billing, output, and context window

1978 limits.

1979 

1980 - `prompt_tokens_details: optional object { audio_tokens, cached_tokens }`

1981 

1982 Breakdown of tokens used in the prompt.

1983 

1984 - `audio_tokens: optional number`

1985 

1986 Audio input tokens present in the prompt.

1987 

1988 - `cached_tokens: optional number`

1989 

1990 Cached tokens present in the prompt.

1991 

1992### Example

1993 

1994```cli

1995openai chat:completions update \

1996 --api-key 'My API Key' \