Update chat completion

Modify a stored chat completion. Only Chat Completions that have been created with the store parameter set to true can be modified. Currently, the only supported modification is to update the metadata field.

POST /chat/completions/{completion_id}

Update chat completion

cURL

curl --request POST \
  --url https://api.openai.com/v1/chat/completions/{completion_id} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "metadata": {}
}'

200

{
  "id": "<string>",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 123,
      "message": {
        "content": "<string>",
        "refusal": "<string>",
        "role": "assistant",
        "tool_calls": [
          {
            "id": "<string>",
            "type": "function",
            "function": {
              "name": "<string>",
              "arguments": "<string>"
            }
          }
        ],
        "annotations": [
          {
            "type": "url_citation",
            "url_citation": {
              "end_index": 123,
              "start_index": 123,
              "url": "<string>",
              "title": "<string>"
            }
          }
        ],
        "function_call": {
          "arguments": "<string>",
          "name": "<string>"
        },
        "audio": {
          "id": "<string>",
          "expires_at": 123,
          "data": "<string>",
          "transcript": "<string>"
        }
      },
      "logprobs": {
        "content": [
          {
            "token": "<string>",
            "logprob": 123,
            "bytes": [
              123
            ],
            "top_logprobs": [
              {
                "token": "<string>",
                "logprob": 123,
                "bytes": [
                  123
                ]
              }
            ]
          }
        ],
        "refusal": [
          {
            "token": "<string>",
            "logprob": 123,
            "bytes": [
              123
            ],
            "top_logprobs": [
              {
                "token": "<string>",
                "logprob": 123,
                "bytes": [
                  123
                ]
              }
            ]
          }
        ]
      }
    }
  ],
  "created": 123,
  "model": "<string>",
  "object": "chat.completion",
  "service_tier": "auto",
  "system_fingerprint": "<string>",
  "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
    }
  }
}

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

completion_id · string · required

The ID of the chat completion to update.

Body

application/json

metadata · object · required

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.

Show child attributes

Response

200 - application/json

A chat completion

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

id · string · required

A unique identifier for the chat completion.

choices · object[] · required

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

Show child attributes

created · integer · required

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

model · string · required

The model used for the chat completion.

object · enum<string> · required

The object type, which is always chat.completion.

Available options: chat.completion

service_tier · enum<string> | null · default: auto

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

Available options: auto, default, economy

system_fingerprint · 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 · object

Usage statistics for the completion request.

Show child attributes