Response Formats

Overview

The Chat Completions API returns responses in a structured JSON format. Each response contains metadata about the request, the generated message(s), and usage statistics. Understanding the response structure is essential for properly parsing and utilizing the API results in your application.

Response Structure

The complete response object contains the following fields:

Root Level Fields

Field	Type	Description
`id`	string	A unique identifier for the chat completion request. This ID can be used for tracking and debugging purposes.
`object`	string	The type of object returned. Always set to `"chat.completion"` for chat completion responses.
`created`	integer	The Unix timestamp (in seconds) when the response was generated.
`model`	string	The model that was used to generate the completion (e.g., `"gpt-4"`, `"gpt-3.5-turbo"`).
`choices`	array	An array of completion choices. Contains one or more generated responses.
`usage`	object	Token usage statistics for the request and response.

Choices Array

Each item in the choices array represents a generated completion and contains the following fields:

Field	Type	Description
`index`	integer	The index of the choice in the choices array. Starts at 0.
`message`	object	The message object containing the generated response.
`finish_reason`	string	The reason why the model stopped generating tokens. Possible values: `"stop"`, `"length"`, `"content_filter"`, `"tool_calls"`, or `"function_call"`.

Message Object

The message object within each choice contains:

Field	Type	Description
`role`	string	The role of the message author. Always `"assistant"` for generated responses.
`content`	string	The actual content of the assistant's message. This contains the generated text response.

Usage Object

The usage object provides token usage information:

Field	Type	Description
`prompt_tokens`	integer	The number of tokens used in the prompt (input).
`completion_tokens`	integer	The number of tokens generated in the completion (output).
`total_tokens`	integer	The total number of tokens used (prompt + completion).

Example Responses

Basic Response Example

{
  "id": "chatcmpl-1234567890abcdef",
  "object": "chat.completion",
  "created": 1738886400,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Hello! How can I help you today?"
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 9,
    "total_tokens": 19
  }
}

Multi-Choice Response Example

{
  "id": "chatcmpl-0987654321fedcba",
  "object": "chat.completion",
  "created": 1738886400,
  "model": "gpt-3.5-turbo",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "The capital of France is Paris."
      },
      "finish_reason": "stop"
    },
    {
      "index": 1,
      "message": {
        "role": "assistant",
        "content": "Paris is the capital city of France."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 15,
    "completion_tokens": 25,
    "total_tokens": 40
  }
}

Response with Length Stop Reason

{
  "id": "chatcmpl-5432109876zyxwvu",
  "object": "chat.completion",
  "created": 1738886400,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "This is a long response that was cut off due to reaching the maximum token limit specified in the request..."
      },
      "finish_reason": "length"
    }
  ],
  "usage": {
    "prompt_tokens": 20,
    "completion_tokens": 4096,
    "total_tokens": 4116
  }
}

Finish Reasons

The finish_reason field indicates why the model stopped generating:

Finish Reason	Description
`stop`	The model reached a natural stopping point (end of a sentence, paragraph, or logical conclusion).
`length`	The model reached the maximum number of tokens specified in the `max_tokens` parameter.
`content_filter`	The response was flagged by content filters and was omitted.
`tool_calls`	The model decided to make a tool call instead of generating text.
`function_call`	(Legacy) The model decided to make a function call instead of generating text.

Handling Responses

Error Responses

If an error occurs, the API returns an HTTP error status code along with a JSON error object:

{
  "error": {
    "message": "Invalid API key provided",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}

Best Practices

Always check the finish_reason to understand why generation stopped
Monitor usage statistics to track token consumption and manage costs
Handle the id field for request tracking and debugging
Validate the response structure before parsing to handle unexpected errors
Implement retry logic for transient errors (5xx status codes)

Streaming Responses

When using the streaming API, responses are delivered as Server-Sent Events (SSE) with the same structure but incrementally. Each chunk contains a partial choices array with deltas instead of complete messages.

Streaming Chunk Example

{
  "id": "chatcmpl-1234567890abcdef",
  "object": "chat.completion.chunk",
  "created": 1738886400,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "delta": {
        "content": "Hello"
      },
      "finish_reason": null
    }
  ]
}

The final chunk in a stream will have finish_reason set and an empty delta:

{
  "id": "chatcmpl-1234567890abcdef",
  "object": "chat.completion.chunk",
  "created": 1738886400,
  "model": "gpt-4",
  "choices": [
    {
      "index": 0,
      "delta": {},
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 10,
    "completion_tokens": 9,
    "total_tokens": 19
  }
}