resources/chat/subresources/completions/methods/retrieve/index.md

Get chat completion

get /chat/completions/{completion_id}

Get a stored chat completion. Only Chat Completions that have been created with the store parameter set to true will be returned.

Path Parameters

completion_id: string

Returns

ChatCompletion object { id, choices, created, 6 more }

Represents a chat completion response returned by model, based on the provided input.
- id: string
  
  A unique identifier for the chat completion.
- choices: array of object { finish_reason, index, logprobs, message }
  
  A list of chat completion choices. Can be more than one if n is greater than 1.
  - finish_reason: "stop" or "length" or "tool_calls" or 2 more
    
    The reason the model stopped generating tokens. This will be stop if the model hit a natural stop point or a provided stop sequence, length if the maximum number of tokens specified in the request was reached, content_filter if content was omitted due to a flag from our content filters, tool_calls if the model called a tool, or function_call (deprecated) if the model called a function. Read the Model Spec for more.
    - "stop"
    - "length"
    - "tool_calls"
    - "content_filter"
    - "function_call"
  - index: number
    
    The index of the choice in the list of choices.
  - logprobs: object { content, refusal }
    
    Log probability information for the choice.
    - content: array of ChatCompletionTokenLogprob
      
      A list of message content tokens with log probability information.
      - token: string
        
        The token.
      - bytes: array of number
        
        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.
      - logprob: number
        
        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.
      - top_logprobs: array of object { token, bytes, logprob }
        
        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.
        
        token: string
        
        The token.
        
        bytes: array of number
        
        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.
        
        logprob: number
        
        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.
    - refusal: array of ChatCompletionTokenLogprob
      
      A list of message refusal tokens with log probability information.
      - token: string
        
        The token.
      - bytes: array of number
        
        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.
      - logprob: number
        
        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.
      - top_logprobs: array of object { token, bytes, logprob }
        
        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.
  - message: ChatCompletionMessage
    
    A chat completion message generated by the model.
    - content: string
      
      The contents of the message.
    - refusal: string
      
      The refusal message generated by the model.
    - role: "assistant"
      
      The role of the author of this message.
      - "assistant"
    - annotations: optional array of object { type, url_citation }
      
      Annotations for the message, when applicable, as when using the web search tool.
      - type: "url_citation"
        
        The type of the URL citation. Always url_citation.
        
        "url_citation"
      - url_citation: object { end_index, start_index, title, url }
        
        A URL citation when using web search.
        
        end_index: number
        
        The index of the last character of the URL citation in the message.
        
        start_index: number
        
        The index of the first character of the URL citation in the message.
        
        title: string
        
        The title of the web resource.
        
        url: string
        
        The URL of the web resource.
    - audio: optional ChatCompletionAudio
      
      If the audio output modality is requested, this object contains data about the audio response from the model. Learn more.
      - id: string
        
        Unique identifier for this audio response.
      - data: string
        
        Base64 encoded audio bytes generated by the model, in the format specified in the request.
      - expires_at: number
        
        The Unix timestamp (in seconds) for when this audio response will no longer be accessible on the server for use in multi-turn conversations.
      - transcript: string
        
        Transcript of the audio generated by the model.
    - function_call: optional object { arguments, name }
      
      Deprecated and replaced by tool_calls. The name and arguments of a function that should be called, as generated by the model.
      - arguments: string
        
        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.
      - name: string
        
        The name of the function to call.
    - tool_calls: optional array of ChatCompletionMessageToolCall
      
      The tool calls generated by the model, such as function calls.
      - ChatCompletionMessageFunctionToolCall object { id, function, type }
        
        A call to a function tool created by the model.
        
        id: string
        
        The ID of the tool call.
        
        function: object { arguments, name }
        
        The function that the model called.
        
        arguments: string
        
        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.
        
        name: string
        
        The name of the function to call.
        
        type: "function"
        
        The type of the tool. Currently, only function is supported.
        
        "function"
      - ChatCompletionMessageCustomToolCall object { id, custom, type }
        
        A call to a custom tool created by the model.
        
        id: string
        
        The ID of the tool call.
        
        custom: object { input, name }
        
        The custom tool that the model called.
        
        input: string
        
        The input for the custom tool call generated by the model.
        
        name: string
        
        The name of the custom tool to call.
        
        type: "custom"
        
        The type of the tool. Always custom.
        
        "custom"
- created: number
  
  The Unix timestamp (in seconds) of when the chat completion was created.
- model: string
  
  The model used for the chat completion.
- object: "chat.completion"
  
  The object type, which is always chat.completion.
  - "chat.completion"
- moderation: optional object { input, output }
  
  Moderation results for the request input and generated output, if moderated completions were requested.
  - input: object { model, results, type } or object { code, message, type }
    
    Moderation for the request input.
    - ModerationResults object { model, results, type }
      
      Successful moderation results for the request input or generated output.
      - model: string
        
        The moderation model used to generate the results.
      - results: array of object { categories, category_applied_input_types, category_scores, 3 more }
        
        A list of moderation results.
        
        categories: map[boolean]
        
        A dictionary of moderation categories to booleans, True if the input is flagged under this category.
        
        category_applied_input_types: map[array of "text" or "image"]
        
        Which modalities of input are reflected by the score for each category.
        
        "text"
        
        "image"
        
        category_scores: map[number]
        
        A dictionary of moderation categories to scores.
        
        flagged: boolean
        
        A boolean indicating whether the content was flagged by any category.
        
        model: string
        
        The moderation model that produced this result.
        
        type: "moderation_result"
        
        The object type, which was always moderation_result for successful moderation results.
        
        "moderation_result"
      - type: "moderation_results"
        
        The object type, which is always moderation_results.
        
        "moderation_results"
    - Error object { code, message, type }
      
      An error produced while attempting moderation.
      - code: string
        
        The error code.
      - message: string
        
        The error message.
      - type: "error"
        
        The object type, which is always error.
        
        "error"
  - output: object { model, results, type } or object { code, message, type }
    
    Moderation for the generated output.
    - ModerationResults object { model, results, type }
      
      Successful moderation results for the request input or generated output.
      - model: string
        
        The moderation model used to generate the results.
      - results: array of object { categories, category_applied_input_types, category_scores, 3 more }
        
        A list of moderation results.
        
        categories: map[boolean]
        
        A dictionary of moderation categories to booleans, True if the input is flagged under this category.
        
        category_applied_input_types: map[array of "text" or "image"]
        
        Which modalities of input are reflected by the score for each category.
        
        "text"
        
        "image"
        
        category_scores: map[number]
        
        A dictionary of moderation categories to scores.
        
        flagged: boolean
        
        A boolean indicating whether the content was flagged by any category.
        
        model: string
        
        The moderation model that produced this result.
        
        type: "moderation_result"
        
        The object type, which was always moderation_result for successful moderation results.
        
        "moderation_result"
      - type: "moderation_results"
        
        The object type, which is always moderation_results.
        
        "moderation_results"
    - Error object { code, message, type }
      
      An error produced while attempting moderation.
      - code: string
        
        The error code.
      - message: string
        
        The error message.
      - type: "error"
        
        The object type, which is always error.
        
        "error"
- service_tier: optional "auto" or "default" or "flex" or 2 more
  
  Specifies the processing type used for serving the request.
  - 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'.
  - If set to 'default', then the request will be processed with the standard pricing and performance for the selected model.
  - If set to 'flex' or 'priority', then the request will be processed with the corresponding service tier.
  - When not set, the default behavior is 'auto'.
  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.
  - "auto"
  - "default"
  - "flex"
  - "scale"
  - "priority"
- system_fingerprint: optional string
  
  This fingerprint represents the backend configuration that the model runs with.
  
  Can be used in conjunction with the seed request parameter to understand when backend changes have been made that might impact determinism.
- usage: optional CompletionUsage
  
  Usage statistics for the completion request.
  - completion_tokens: number
    
    Number of tokens in the generated completion.
  - prompt_tokens: number
    
    Number of tokens in the prompt.
  - total_tokens: number
    
    Total number of tokens used in the request (prompt + completion).
  - completion_tokens_details: optional object { accepted_prediction_tokens, audio_tokens, reasoning_tokens, rejected_prediction_tokens }
    
    Breakdown of tokens used in a completion.
    - accepted_prediction_tokens: optional number
      
      When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion.
    - audio_tokens: optional number
      
      Audio input tokens generated by the model.
    - reasoning_tokens: optional number
      
      Tokens generated by the model for reasoning.
    - rejected_prediction_tokens: optional number
      
      When using Predicted Outputs, the number of tokens in the prediction that did not appear in the completion. However, like reasoning tokens, these tokens are still counted in the total completion tokens for purposes of billing, output, and context window limits.
  - prompt_tokens_details: optional object { audio_tokens, cached_tokens }
    
    Breakdown of tokens used in the prompt.
    - audio_tokens: optional number
      
      Audio input tokens present in the prompt.
    - cached_tokens: optional number
      
      Cached tokens present in the prompt.

Example

curl https://api.openai.com/v1/chat/completions/$COMPLETION_ID \
    -H "Authorization: Bearer $OPENAI_API_KEY"

Response

{
  "id": "id",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 0,
      "logprobs": {
        "content": [
          {
            "token": "token",
            "bytes": [
              0
            ],
            "logprob": 0,
            "top_logprobs": [
              {
                "token": "token",
                "bytes": [
                  0
                ],
                "logprob": 0
              }
            ]
          }
        ],
        "refusal": [
          {
            "token": "token",
            "bytes": [
              0
            ],
            "logprob": 0,
            "top_logprobs": [
              {
                "token": "token",
                "bytes": [
                  0
                ],
                "logprob": 0
              }
            ]
          }
        ]
      },
      "message": {
        "content": "content",
        "refusal": "refusal",
        "role": "assistant",
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "end_index": 0,
              "start_index": 0,
              "title": "title",
              "url": "https://example.com"
            }
          }
        ],
        "audio": {
          "id": "id",
          "data": "data",
          "expires_at": 0,
          "transcript": "transcript"
        },
        "function_call": {
          "arguments": "arguments",
          "name": "name"
        },
        "tool_calls": [
          {
            "id": "id",
            "function": {
              "arguments": "arguments",
              "name": "name"
            },
            "type": "function"
          }
        ]
      }
    }
  ],
  "created": 0,
  "model": "model",
  "object": "chat.completion",
  "moderation": {
    "input": {
      "model": "model",
      "results": [
        {
          "categories": {
            "foo": true
          },
          "category_applied_input_types": {
            "foo": [
              "text"
            ]
          },
          "category_scores": {
            "foo": 0
          },
          "flagged": true,
          "model": "model",
          "type": "moderation_result"
        }
      ],
      "type": "moderation_results"
    },
    "output": {
      "model": "model",
      "results": [
        {
          "categories": {
            "foo": true
          },
          "category_applied_input_types": {
            "foo": [
              "text"
            ]
          },
          "category_scores": {
            "foo": 0
          },
          "flagged": true,
          "model": "model",
          "type": "moderation_result"
        }
      ],
      "type": "moderation_results"
    }
  },
  "service_tier": "auto",
  "system_fingerprint": "system_fingerprint",
  "usage": {
    "completion_tokens": 0,
    "prompt_tokens": 0,
    "total_tokens": 0,
    "completion_tokens_details": {
      "accepted_prediction_tokens": 0,
      "audio_tokens": 0,
      "reasoning_tokens": 0,
      "rejected_prediction_tokens": 0
    },
    "prompt_tokens_details": {
      "audio_tokens": 0,
      "cached_tokens": 0
    }
  }
}

Example

curl https://api.openai.com/v1/chat/completions/chatcmpl-abc123 \
  -H "Authorization: Bearer $OPENAI_API_KEY" \
  -H "Content-Type: application/json"

Response

{
  "object": "chat.completion",
  "id": "chatcmpl-abc123",
  "model": "gpt-4o-2024-08-06",
  "created": 1738960610,
  "request_id": "req_ded8ab984ec4bf840f37566c1011c417",
  "tool_choice": null,
  "usage": {
    "total_tokens": 31,
    "completion_tokens": 18,
    "prompt_tokens": 13
  },
  "seed": 4944116822809979520,
  "top_p": 1.0,
  "temperature": 1.0,
  "presence_penalty": 0.0,
  "frequency_penalty": 0.0,
  "system_fingerprint": "fp_50cad350e4",
  "input_user": null,
  "service_tier": "default",
  "tools": null,
  "metadata": {},
  "choices": [
    {
      "index": 0,
      "message": {
        "content": "Mind of circuits hum,  \nLearning patterns in silence—  \nFuture's quiet spark.",
        "role": "assistant",
        "tool_calls": null,
        "function_call": null
      },
      "finish_reason": "stop",
      "logprobs": null
    }
  ],
  "response_format": null
}

resources/chat/subresources/completions/methods/retrieve/index.md +193 −1

11 11

12### Returns12### Returns

13 13

~~14- `ChatCompletion object { id, choices, created, 5 more }`~~14- `ChatCompletion object { id, choices, created, 6 more }`

15 15

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

17 17

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

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

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

32 Read the [Model Spec](https://model-spec.openai.com/2025-12-18.html) for more.

32 33

33 - `"stop"`34 - `"stop"`

34 35

255 256

256 - `"chat.completion"`257 - `"chat.completion"`

257 258

259 - `moderation: optional object { input, output }`

260

261 Moderation results for the request input and generated output, if moderated

262 completions were requested.

263

264 - `input: object { model, results, type } or object { code, message, type }`

265

266 Moderation for the request input.

267

268 - `ModerationResults object { model, results, type }`

269

270 Successful moderation results for the request input or generated output.

271

272 - `model: string`

273

274 The moderation model used to generate the results.

275

276 - `results: array of object { categories, category_applied_input_types, category_scores, 3 more }`

277

278 A list of moderation results.

279

280 - `categories: map[boolean]`

281

282 A dictionary of moderation categories to booleans, True if the input is flagged under this category.

283

284 - `category_applied_input_types: map[array of "text" or "image"]`

285

286 Which modalities of input are reflected by the score for each category.

287

288 - `"text"`

289

290 - `"image"`

291

292 - `category_scores: map[number]`

293

294 A dictionary of moderation categories to scores.

295

296 - `flagged: boolean`

297

298 A boolean indicating whether the content was flagged by any category.

299

300 - `model: string`

301

302 The moderation model that produced this result.

303

304 - `type: "moderation_result"`

305

306 The object type, which was always `moderation_result` for successful moderation results.

307

308 - `"moderation_result"`

309

310 - `type: "moderation_results"`

311

312 The object type, which is always `moderation_results`.

313

314 - `"moderation_results"`

315

316 - `Error object { code, message, type }`

317

318 An error produced while attempting moderation.

319

320 - `code: string`

321

322 The error code.

323

324 - `message: string`

325

326 The error message.

327

328 - `type: "error"`

329

330 The object type, which is always `error`.

331

332 - `"error"`

333

334 - `output: object { model, results, type } or object { code, message, type }`

335

336 Moderation for the generated output.

337

338 - `ModerationResults object { model, results, type }`

339

340 Successful moderation results for the request input or generated output.

341

342 - `model: string`

343

344 The moderation model used to generate the results.

345

346 - `results: array of object { categories, category_applied_input_types, category_scores, 3 more }`

347

348 A list of moderation results.

349

350 - `categories: map[boolean]`

351

352 A dictionary of moderation categories to booleans, True if the input is flagged under this category.

353

354 - `category_applied_input_types: map[array of "text" or "image"]`

355

356 Which modalities of input are reflected by the score for each category.

357

358 - `"text"`

359

360 - `"image"`

361

362 - `category_scores: map[number]`

363

364 A dictionary of moderation categories to scores.

365

366 - `flagged: boolean`

367

368 A boolean indicating whether the content was flagged by any category.

369

370 - `model: string`

371

372 The moderation model that produced this result.

373

374 - `type: "moderation_result"`

375

376 The object type, which was always `moderation_result` for successful moderation results.

377

378 - `"moderation_result"`

379

380 - `type: "moderation_results"`

381

382 The object type, which is always `moderation_results`.

383

384 - `"moderation_results"`

385

386 - `Error object { code, message, type }`

387

388 An error produced while attempting moderation.

389

390 - `code: string`

391

392 The error code.

393

394 - `message: string`

395

396 The error message.

397

398 - `type: "error"`

399

400 The object type, which is always `error`.

401

402 - `"error"`

403

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

259 405

260 Specifies the processing type used for serving the request.406 Specifies the processing type used for serving the request.

430 "created": 0,576 "created": 0,

431 "model": "model",577 "model": "model",

432 "object": "chat.completion",578 "object": "chat.completion",

579 "moderation": {

580 "input": {

581 "model": "model",

582 "results": [

583 {

584 "categories": {

585 "foo": true

586 },

587 "category_applied_input_types": {

588 "foo": [

589 "text"

590 ]

591 },

592 "category_scores": {

593 "foo": 0

594 },

595 "flagged": true,

596 "model": "model",

597 "type": "moderation_result"

598 }

599 ],

600 "type": "moderation_results"

601 },

602 "output": {

603 "model": "model",

604 "results": [

605 {

606 "categories": {

607 "foo": true

608 },

609 "category_applied_input_types": {

610 "foo": [

611 "text"

612 ]

613 },

614 "category_scores": {

615 "foo": 0

616 },

617 "flagged": true,

618 "model": "model",

619 "type": "moderation_result"

620 }

621 ],

622 "type": "moderation_results"

623 }

624 },

433 "service_tier": "auto",625 "service_tier": "auto",

434 "system_fingerprint": "system_fingerprint",626 "system_fingerprint": "system_fingerprint",

435 "usage": {627 "usage": {

resources/chat/subresources/completions/methods/retrieve/index.md 2026-06-02 06:51 UTC to 2026-06-04 06:52 UTC

Get chat completion

Path Parameters

Returns

Example

Response

Example

Response