> ## Documentation Index > Fetch the complete documentation index at: https://openai-hd4n6.mintlify.site/llms.txt > Use this file to discover all available pages before exploring further. # List Chat Completions > List stored Chat Completions. Only Chat Completions that have been stored with the `store` parameter set to `true` will be returned. ## OpenAPI ````yaml api-definition.yaml get /chat/completions openapi: 3.0.0 info: title: OpenAI API description: >- The OpenAI REST API. Please see https://platform.openai.com/docs/api-reference for more details. version: 2.3.0 termsOfService: https://openai.com/policies/terms-of-use contact: name: OpenAI Support url: https://help.openai.com/ license: name: MIT url: https://github.com/openai/openai-openapi/blob/master/LICENSE servers: - url: https://api.openai.com/v1 security: - ApiKeyAuth: [] tags: - name: Assistants description: Build Assistants that can call models and use tools. - name: Audio description: Turn audio into text or text into audio. - name: Chat description: >- Given a list of messages comprising a conversation, the model will return a response. - name: Completions description: >- Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position. - name: Embeddings description: >- Get a vector representation of a given input that can be easily consumed by machine learning models and algorithms. - name: Evals description: Manage and run evals in the OpenAI platform. - name: Fine-tuning description: Manage fine-tuning jobs to tailor a model to your specific training data. - name: Batch description: Create large batches of API requests to run asynchronously. - name: Files description: >- Files are used to upload documents that can be used with features like Assistants and Fine-tuning. - name: Uploads description: Use Uploads to upload large files in multiple parts. - name: Images description: Given a prompt and/or an input image, the model will generate a new image. - name: Models description: List and describe the various models available in the API. - name: Moderations description: >- Given text and/or image inputs, classifies if those inputs are potentially harmful. - name: Audit Logs description: List user actions and configuration changes within this organization. paths: /chat/completions: get: tags: - Chat summary: List Chat Completions description: > List stored Chat Completions. Only Chat Completions that have been stored with the `store` parameter set to `true` will be returned. operationId: listChatCompletions parameters: - name: model in: query description: The model used to generate the Chat Completions. required: false schema: type: string - name: metadata in: query description: | A list of metadata keys to filter the Chat Completions by. Example: `metadata[key1]=value1&metadata[key2]=value2` required: false schema: $ref: '#/components/schemas/Metadata' - name: after in: query description: >- Identifier for the last chat completion from the previous pagination request. required: false schema: type: string - name: limit in: query description: Number of Chat Completions to retrieve. required: false schema: type: integer default: 20 - name: order in: query description: >- Sort order for Chat Completions by timestamp. Use `asc` for ascending order or `desc` for descending order. Defaults to `asc`. required: false schema: type: string enum: - asc - desc default: asc responses: '200': description: A list of Chat Completions content: application/json: schema: $ref: '#/components/schemas/ChatCompletionList' components: schemas: Metadata: type: object description: > Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured format, and querying for objects via API or the dashboard. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. additionalProperties: type: string x-oaiTypeLabel: map nullable: true ChatCompletionList: type: object title: ChatCompletionList description: | An object representing a list of Chat Completions. properties: object: type: string enum: - list default: list description: | The type of this object. It is always set to "list". x-stainless-const: true data: type: array description: | An array of chat completion objects. items: $ref: '#/components/schemas/CreateChatCompletionResponse' first_id: type: string description: The identifier of the first chat completion in the data array. last_id: type: string description: The identifier of the last chat completion in the data array. has_more: type: boolean description: Indicates whether there are more Chat Completions available. required: - object - data - first_id - last_id - has_more x-oaiMeta: name: The chat completion list object group: chat example: | { "object": "list", "data": [ { "object": "chat.completion", "id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "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 } ], "first_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "last_id": "chatcmpl-AyPNinnUqUDYo9SAdA52NobMflmj2", "has_more": false } CreateChatCompletionResponse: type: object description: >- Represents a chat completion response returned by model, based on the provided input. properties: id: type: string description: A unique identifier for the chat completion. choices: type: array description: >- A list of chat completion choices. Can be more than one if `n` is greater than 1. items: type: object required: - finish_reason - index - message - logprobs properties: finish_reason: type: string description: > 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. enum: - stop - length - tool_calls - content_filter - function_call index: type: integer description: The index of the choice in the list of choices. message: $ref: '#/components/schemas/ChatCompletionResponseMessage' logprobs: description: Log probability information for the choice. type: object nullable: true properties: content: description: >- A list of message content tokens with log probability information. type: array items: $ref: '#/components/schemas/ChatCompletionTokenLogprob' nullable: true refusal: description: >- A list of message refusal tokens with log probability information. type: array items: $ref: '#/components/schemas/ChatCompletionTokenLogprob' nullable: true required: - content - refusal created: type: integer description: >- The Unix timestamp (in seconds) of when the chat completion was created. model: type: string description: The model used for the chat completion. service_tier: $ref: '#/components/schemas/ServiceTier' system_fingerprint: type: string description: > 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. object: type: string description: The object type, which is always `chat.completion`. enum: - chat.completion x-stainless-const: true usage: $ref: '#/components/schemas/CompletionUsage' required: - choices - created - id - model - object x-oaiMeta: name: The chat completion object group: chat example: | { "id": "chatcmpl-B9MHDbslfkBeAs8l4bebGdFOJ6PeG", "object": "chat.completion", "created": 1741570283, "model": "gpt-4o-2024-08-06", "choices": [ { "index": 0, "message": { "role": "assistant", "content": "The image shows a wooden boardwalk path running through a lush green field or meadow. The sky is bright blue with some scattered clouds, giving the scene a serene and peaceful atmosphere. Trees and shrubs are visible in the background.", "refusal": null, "annotations": [] }, "logprobs": null, "finish_reason": "stop" } ], "usage": { "prompt_tokens": 1117, "completion_tokens": 46, "total_tokens": 1163, "prompt_tokens_details": { "cached_tokens": 0, "audio_tokens": 0 }, "completion_tokens_details": { "reasoning_tokens": 0, "audio_tokens": 0, "accepted_prediction_tokens": 0, "rejected_prediction_tokens": 0 } }, "service_tier": "default", "system_fingerprint": "fp_fc9f1d7035" } ChatCompletionResponseMessage: type: object description: A chat completion message generated by the model. properties: content: type: string description: The contents of the message. nullable: true refusal: type: string description: The refusal message generated by the model. nullable: true tool_calls: $ref: '#/components/schemas/ChatCompletionMessageToolCalls' annotations: type: array description: | Annotations for the message, when applicable, as when using the [web search tool](/docs/guides/tools-web-search?api-mode=chat). items: type: object description: | A URL citation when using web search. required: - type - url_citation properties: type: type: string description: The type of the URL citation. Always `url_citation`. enum: - url_citation x-stainless-const: true url_citation: type: object description: A URL citation when using web search. required: - end_index - start_index - url - title properties: end_index: type: integer description: >- The index of the last character of the URL citation in the message. start_index: type: integer description: >- The index of the first character of the URL citation in the message. url: type: string description: The URL of the web resource. title: type: string description: The title of the web resource. role: type: string enum: - assistant description: The role of the author of this message. x-stainless-const: true function_call: type: object deprecated: true description: >- Deprecated and replaced by `tool_calls`. The name and arguments of a function that should be called, as generated by the model. properties: arguments: type: string description: >- 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: type: string description: The name of the function to call. required: - name - arguments audio: type: object nullable: true description: > If the audio output modality is requested, this object contains data about the audio response from the model. [Learn more](/docs/guides/audio). x-oaiExpandable: true required: - id - expires_at - data - transcript properties: id: type: string description: Unique identifier for this audio response. expires_at: type: integer description: > The Unix timestamp (in seconds) for when this audio response will no longer be accessible on the server for use in multi-turn conversations. data: type: string description: | Base64 encoded audio bytes generated by the model, in the format specified in the request. transcript: type: string description: Transcript of the audio generated by the model. required: - role - content - refusal ChatCompletionTokenLogprob: type: object properties: token: description: The token. type: string logprob: description: >- 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. type: number bytes: description: >- 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. type: array items: type: integer nullable: true top_logprobs: description: >- List of the most likely tokens and their log probability, at this token position. In rare cases, there may be fewer than the number of requested `top_logprobs` returned. type: array items: type: object properties: token: description: The token. type: string logprob: description: >- 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. type: number bytes: description: >- 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. type: array items: type: integer nullable: true required: - token - logprob - bytes required: - token - logprob - bytes - top_logprobs ServiceTier: type: string description: > Specifies the latency tier to use for processing the request. This parameter is relevant for customers subscribed to the scale tier service: - If set to 'auto', and the Project is Scale tier enabled, the system will utilize scale tier credits until they are exhausted. - If set to 'auto', and the Project is not Scale tier enabled, the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'default', the request will be processed using the default service tier with a lower uptime SLA and no latency guarentee. - If set to 'economy', the request will be processed with the Economy service tier at the specified price. Economy requests have longer response times and may experience Resource Unavailable errors. See [the docs](/docs/guides/economy-tier) for more information. - When not set, the default behavior is 'auto'. When this parameter is set, the response body will include the `service_tier` utilized. enum: - auto - default - economy nullable: true default: auto CompletionUsage: type: object description: Usage statistics for the completion request. properties: completion_tokens: type: integer default: 0 description: Number of tokens in the generated completion. prompt_tokens: type: integer default: 0 description: Number of tokens in the prompt. total_tokens: type: integer default: 0 description: Total number of tokens used in the request (prompt + completion). completion_tokens_details: type: object description: Breakdown of tokens used in a completion. properties: accepted_prediction_tokens: type: integer default: 0 description: | When using Predicted Outputs, the number of tokens in the prediction that appeared in the completion. audio_tokens: type: integer default: 0 description: Audio input tokens generated by the model. reasoning_tokens: type: integer default: 0 description: Tokens generated by the model for reasoning. rejected_prediction_tokens: type: integer default: 0 description: > 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: type: object description: Breakdown of tokens used in the prompt. properties: audio_tokens: type: integer default: 0 description: Audio input tokens present in the prompt. cached_tokens: type: integer default: 0 description: Cached tokens present in the prompt. required: - prompt_tokens - completion_tokens - total_tokens ChatCompletionMessageToolCalls: type: array description: The tool calls generated by the model, such as function calls. items: $ref: '#/components/schemas/ChatCompletionMessageToolCall' ChatCompletionMessageToolCall: type: object properties: id: type: string description: The ID of the tool call. type: type: string enum: - function description: The type of the tool. Currently, only `function` is supported. x-stainless-const: true function: type: object description: The function that the model called. properties: name: type: string description: The name of the function to call. arguments: type: string description: >- 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. required: - name - arguments required: - id - type - function securitySchemes: ApiKeyAuth: type: http scheme: bearer ````