> ## Documentation Index
> Fetch the complete documentation index at: https://developer.swytcho.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Swytcho API Response Format: Fields and Finish Reasons

> Decode every field in a Swytcho API response — the envelope, choices array, usage object, finish reasons, and what each tells you about your completion.

Swytcho returns JSON responses with a consistent envelope structure across all completion endpoints. Understanding each field helps you extract content reliably, handle edge cases gracefully, and track token consumption for cost management.

## Response Envelope

Every non-streaming response from the chat completions endpoint shares the following top-level fields.

<ResponseField name="id" type="string">
  A unique identifier for this completion request, prefixed with `chatcmpl-`. Use this ID when reporting issues to Swytcho support.
</ResponseField>

<ResponseField name="object" type="string">
  The type of object returned. For chat completions this is always `"chat.completion"`.
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp (seconds) of when the completion was generated.
</ResponseField>

<ResponseField name="model" type="string">
  The exact model ID used to generate the response, including any date-pinned version suffix (e.g., `"swytcho-1-2025-04-01"`). This may differ from the alias you requested if the alias was resolved to a pinned version.
</ResponseField>

<ResponseField name="choices" type="array">
  An array of completion candidates. Most requests return a single choice (`choices[0]`). See [The `choices` Array](#the-choices-array) below for the full structure of each element.
</ResponseField>

<ResponseField name="usage" type="object">
  Token consumption statistics for the request. See [The `usage` Object](#the-usage-object) below.
</ResponseField>

## The `choices` Array

Each element of `choices` represents one candidate completion.

<ResponseField name="choices[n].index" type="integer">
  Zero-based index of this choice in the array.
</ResponseField>

<ResponseField name="choices[n].message" type="object">
  The generated message. Contains a `role` field (always `"assistant"`) and a `content` field with the text of the completion. When tool calls are present, `content` may be `null` and a `tool_calls` array is populated instead.
</ResponseField>

<ResponseField name="choices[n].finish_reason" type="string">
  The reason the model stopped generating tokens. See [Finish Reasons](#finish-reasons) for all possible values and their meanings.
</ResponseField>

## The `usage` Object

<ResponseField name="usage.prompt_tokens" type="integer">
  Number of tokens in the input prompt, including the system message and all prior conversation turns.
</ResponseField>

<ResponseField name="usage.completion_tokens" type="integer">
  Number of tokens generated in the response.
</ResponseField>

<ResponseField name="usage.total_tokens" type="integer">
  Sum of `prompt_tokens` and `completion_tokens`. This is the value used to calculate the cost of the request.
</ResponseField>

## Full Example Response

```json theme={null}
{
  "id": "chatcmpl-a1b2c3d4e5f6g7h8i9j0",
  "object": "chat.completion",
  "created": 1713042000,
  "model": "swytcho-1-mini",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "Retrieval-augmented generation (RAG) combines a language model with an external knowledge source. At inference time, relevant documents are retrieved and injected into the prompt, allowing the model to produce grounded, up-to-date answers without retraining."
      },
      "finish_reason": "stop"
    }
  ],
  "usage": {
    "prompt_tokens": 42,
    "completion_tokens": 54,
    "total_tokens": 96
  }
}
```

## Finish Reasons

The `finish_reason` field tells you why the model stopped producing tokens. Always check this value before using the response content in downstream logic.

| Value            | Meaning                                                                                                                                             |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `stop`           | The model reached a natural stopping point or encountered a stop sequence you provided. The output is complete.                                     |
| `length`         | The model reached the `max_tokens` limit before finishing. Consider increasing `max_tokens` or shortening your prompt if the output is truncated.   |
| `tool_calls`     | The model generated one or more tool/function calls instead of a text response. Parse `choices[n].message.tool_calls` to handle them.               |
| `content_filter` | The output was blocked by Swytcho's safety filters. The `content` field will be `null` or omitted. Review your prompt for policy-violating content. |

<Note>
  Streaming responses use a different format: the API sends a series of `text/event-stream` chunks, each containing a partial `delta` object rather than a complete `message`. The final chunk includes the `finish_reason`. See the [Streaming guide](/guides/streaming) for a full walkthrough of consuming and reassembling streamed output.
</Note>