Response Structure

~22 min · response, choices, usage

Level 0Tokenizer

0 XP0/54 lessons0/10 achievements

0/120 XP to next level120 XP to go0% complete

Understanding the response object is crucial for production code. Here's a detailed breakdown of what you get back from a Chat Completions call:

finish_reason Values

Value	Meaning
`stop`	Natural end of generation or stop sequence hit
`length`	Hit max_completion_tokens or context window
`tool_calls`	Model wants to call one or more tools
`content_filter`	Stopped by content policy

The usage object now includes detailed breakdowns: prompt_tokens_details.cached_tokens shows cache hits, and completion_tokens_details.reasoning_tokens shows invisible chain-of-thought tokens (billed as output).

Code

Inspecting choices and usage·json

{
  "id": "chatcmpl-B9MBs8CjcvOU2jLn4n570S5qMJKcT",
  "object": "chat.completion",
  "created": 1741569952,
  "model": "gpt-4.1-2025-04-14",
  "choices": [{
    "index": 0,
    "message": {
      "role": "assistant",
      "content": "Hello! How can I assist you today?",
      "refusal": null,
      "annotations": [],
      "tool_calls": null
    },
    "logprobs": null,
    "finish_reason": "stop"
  }],
  "usage": {
    "prompt_tokens": 19,
    "completion_tokens": 10,
    "total_tokens": 29,
    "prompt_tokens_details": { "cached_tokens": 0 },
    "completion_tokens_details": { "reasoning_tokens": 0 }
  }
}

External links

Response object

Exercise

Write a helper unwrap_completion(c) that returns a dict {text, finish_reason, prompt_tokens, completion_tokens, tool_calls?}. Make it null-safe for every field. Use it in 3 places in your code.