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

# POST /v1/chat/completions

> Proxy endpoint for chat completions with authentication and logging

## Overview

The proxy chat completions endpoint provides OpenAI-compatible chat completions with additional features like authentication, rate limiting, budgets, and centralized logging.

## Endpoint

```
POST {PROXY_BASE_URL}/v1/chat/completions
```

Alternate routes:

* `POST /chat/completions`
* `POST /engines/{model}/chat/completions`
* `POST /openai/deployments/{model}/chat/completions`

## Authentication

<ParamField header="Authorization" type="string" required>
  Bearer token for authentication.

  ```
  Authorization: Bearer sk-litellm-xxx...
  ```
</ParamField>

## Request Headers

<ParamField header="Content-Type" type="string" default="application/json">
  Content type of the request body.
</ParamField>

<ParamField header="x-litellm-team-id" type="string">
  Team ID for team-based access control.
</ParamField>

<ParamField header="x-litellm-metadata" type="string">
  JSON stringified metadata for request tracking.
</ParamField>

<ParamField header="x-litellm-user-id" type="string">
  End-user ID for tracking and analytics.
</ParamField>

<ParamField header="x-litellm-tags" type="string">
  Comma-separated tags for request categorization.
</ParamField>

## Request Body

The request body follows the OpenAI chat completions format:

<ParamField body="model" type="string" required>
  Model to use for completion.

  ```json theme={null}
  {"model": "gpt-4"}
  ```
</ParamField>

<ParamField body="messages" type="array" required>
  Array of message objects.

  ```json theme={null}
  {
    "messages": [
      {"role": "system", "content": "You are a helpful assistant."},
      {"role": "user", "content": "Hello!"}
    ]
  }
  ```
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature (0-2).
</ParamField>

<ParamField body="max_tokens" type="integer">
  Maximum tokens to generate.
</ParamField>

<ParamField body="stream" type="boolean" default="false">
  Whether to stream the response.
</ParamField>

<ParamField body="tools" type="array">
  Tools available for function calling.
</ParamField>

See [completion() API](/api/completion) for all available parameters.

## Response

### Success Response (200)

<ResponseField name="id" type="string">
  Unique identifier for the completion.
</ResponseField>

<ResponseField name="object" type="string">
  Object type ("chat.completion" or "chat.completion.chunk" for streaming).
</ResponseField>

<ResponseField name="created" type="integer">
  Unix timestamp of creation.
</ResponseField>

<ResponseField name="model" type="string">
  Model used for the completion.
</ResponseField>

<ResponseField name="choices" type="array">
  Array of completion choices.
</ResponseField>

<ResponseField name="usage" type="object">
  Token usage information.

  <Expandable title="usage object">
    <ResponseField name="prompt_tokens" type="integer">
      Tokens in the prompt.
    </ResponseField>

    <ResponseField name="completion_tokens" type="integer">
      Tokens in the completion.
    </ResponseField>

    <ResponseField name="total_tokens" type="integer">
      Total tokens used.
    </ResponseField>
  </Expandable>
</ResponseField>

### Error Responses

<ResponseField name="401 Unauthorized">
  Invalid or missing authentication token.

  ```json theme={null}
  {
    "error": {
      "message": "Invalid API key",
      "type": "invalid_request_error",
      "code": "invalid_api_key"
    }
  }
  ```
</ResponseField>

<ResponseField name="429 Too Many Requests">
  Rate limit exceeded.

  ```json theme={null}
  {
    "error": {
      "message": "Rate limit exceeded",
      "type": "rate_limit_error"
    }
  }
  ```
</ResponseField>

<ResponseField name="400 Bad Request">
  Invalid request parameters.
</ResponseField>

## Examples

### Basic Request

```bash theme={null}
curl -X POST http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer sk-litellm-xxx" \
  -d '{
    "model": "gpt-4",
    "messages": [
      {"role": "user", "content": "Hello, how are you?"}
    ]
  }'
```

### Python Request

```python theme={null}
import openai

client = openai.OpenAI(
    api_key="sk-litellm-xxx",
    base_url="http://localhost:4000"
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[
        {"role": "user", "content": "Hello!"}
    ]
)

print(response.choices[0].message.content)
```

### Streaming Request

```python theme={null}
import openai

client = openai.OpenAI(
    api_key="sk-litellm-xxx",
    base_url="http://localhost:4000"
)

stream = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Count to 10"}],
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")
```

### With Metadata

```python theme={null}
import openai

client = openai.OpenAI(
    api_key="sk-litellm-xxx",
    base_url="http://localhost:4000"
)

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_headers={
        "x-litellm-user-id": "user-123",
        "x-litellm-metadata": '{"environment": "production"}',
        "x-litellm-tags": "tag1,tag2"
    }
)
```

### Function Calling

```python theme={null}
import openai

client = openai.OpenAI(
    api_key="sk-litellm-xxx",
    base_url="http://localhost:4000"
)

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Get the current weather",
        "parameters": {
            "type": "object",
            "properties": {
                "location": {"type": "string"}
            },
            "required": ["location"]
        }
    }
}]

response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "What's the weather in NYC?"}],
    tools=tools
)
```

## Proxy-Specific Features

### Budget Tracking

The proxy automatically tracks spending against key/team budgets:

```python theme={null}
# Key will be rejected if budget exceeded
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)
# Response includes cost tracking
```

### Rate Limiting

Keys can have TPM (tokens per minute) and RPM (requests per minute) limits:

```python theme={null}
# Requests are automatically throttled
# 429 error returned if limits exceeded
```

### Model Aliases

Use proxy-defined model aliases:

```python theme={null}
response = client.chat.completions.create(
    model="gpt-4",  # Can map to specific deployment
    messages=[{"role": "user", "content": "Hello"}]
)
```

### Automatic Retries & Fallbacks

Proxy handles retries and fallbacks automatically:

```python theme={null}
# If primary deployment fails, proxy tries fallback
response = client.chat.completions.create(
    model="gpt-4",
    messages=[{"role": "user", "content": "Hello"}]
)
```

## Monitoring & Logging

All requests are logged with:

* Request/response details
* Token usage
* Costs
* Latency
* Errors
* User/team information
* Custom metadata

Access logs through:

* Admin UI at `/ui`
* Spend tracking endpoints
* Custom callback integrations

## Related

* [POST /v1/embeddings](/api/proxy/embeddings)
* [Key Management](/api/proxy/keys)
* [Team Management](/api/proxy/teams)
* [Health Endpoints](/api/proxy/health)