# Response Includes

Control which additional data is included in model responses using the `include` parameter. This allows you to access detailed metadata, tool execution results, and debugging information without affecting the core response.

## Overview

By default, model responses contain only the essential output. The `include` parameter lets you opt-in to additional data like source URLs, execution logs, token probabilities, and more. This is useful for:

- **Transparency**: Show users where information comes from
- **Debugging**: Track function executions and token usage
- **Analysis**: Understand model reasoning and confidence
- **Compliance**: Maintain audit trails of tool usage


## Available Include Options

### Tool Call Data

#### `web_search.sources`

Include source URLs, titles, and snippets from web search results.

**Without include:**


```json
{
 "output": [{
 "type": "tool_call",
 "tool_name": "web_search",
 "result": "Latest AI news shows..."
 }]
}
```

**With include:**


```json
{
 "include": ["web_search.sources"],
 "output": [{
 "type": "tool_call",
 "tool_name": "web_search",
 "result": "Latest AI news shows...",
 "sources": [
 {
 "url": "https://example.com/ai-news",
 "title": "AI Breakthroughs 2025",
 "snippet": "Recent developments in...",
 "relevance_score": 0.95,
 "published_date": "2025-01-05"
 }
 ]
 }]
}
```

#### `code_interpreter.outputs`

Include Python execution outputs, printed values, and generated files.

**Example:**


```json
{
 "include": ["code_interpreter.outputs"],
 "output": [{
 "type": "tool_call",
 "tool_name": "code_interpreter",
 "code": "import matplotlib.pyplot as plt\nplt.plot([1,2,3])",
 "outputs": {
 "stdout": "Plot created successfully",
 "stderr": "",
 "files": [
 {
 "id": "file_abc123",
 "name": "plot.png",
 "size": 45678,
 "mime_type": "image/png",
 "url": "https://cdn.freddy.aitronos.com/files/plot.png"
 }
 ],
 "execution_time_ms": 234
 }
 }]
}
```

#### `file_search.results`

Include matched document chunks, relevance scores, and source metadata.

**Example:**


```json
{
 "include": ["file_search.results"],
 "output": [{
 "type": "tool_call",
 "tool_name": "file_search",
 "query": "product pricing",
 "results": [
 {
 "file_id": "file_xyz789",
 "file_name": "pricing_guide.pdf",
 "chunk_text": "Standard plan: $49/month...",
 "page_number": 3,
 "relevance_score": 0.92,
 "metadata": {
 "department": "sales",
 "updated": "2025-01-01"
 }
 }
 ]
 }]
}
```

#### `function_calls.logs`

Include execution logs, timing data, and error details for custom function calls.

**Example:**


```json
{
 "include": ["function_calls.logs"],
 "output": [{
 "type": "function_call",
 "function_name": "get_weather",
 "arguments": {"city": "London"},
 "result": {"temp": 15, "condition": "Cloudy"},
 "logs": {
 "started_at": "2025-01-06T10:30:40.123Z",
 "completed_at": "2025-01-06T10:30:40.456Z",
 "duration_ms": 333,
 "http_status": 200,
 "retries": 0,
 "error": null
 }
 }]
}
```

#### `function_calls.sources`

Include source code context and validation details for function calls.

**Example:**


```json
{
 "include": ["function_calls.sources"],
 "output": [{
 "type": "function_call",
 "function_name": "calculate_total",
 "sources": {
 "function_definition": "def calculate_total(items, tax_rate)...",
 "schema_version": "1.2.0",
 "validation": {
 "passed": true,
 "checked_at": "2025-01-06T10:30:40Z"
 },
 "source_location": "https://github.com/org/repo/blob/main/functions.py#L45"
 }
 }]
}
```

### Message Data

#### `message.input_images`

Include full image URLs from user input messages.

**Example:**


```json
{
 "include": ["message.input_images"],
 "inputs": [{
 "role": "user",
 "content": "What's in this image?",
 "images": [
 {
 "file_id": "file_img123",
 "url": "https://cdn.freddy.aitronos.com/uploads/image.jpg",
 "size": 234567,
 "dimensions": {"width": 1920, "height": 1080},
 "format": "jpeg"
 }
 ]
 }]
}
```

#### `message.output_images`

Include URLs for images generated by the assistant.

**Example:**


```json
{
 "include": ["message.output_images"],
 "output": [{
 "type": "message",
 "role": "assistant",
 "content": "Here's your generated image:",
 "images": [
 {
 "url": "https://cdn.freddy.aitronos.com/generated/img_abc.png",
 "prompt": "A sunset over mountains",
 "model": "dall-e-3",
 "size": "1024x1024"
 }
 ]
 }]
}
```

#### `message.logprobs`

Include token-level probability scores for model outputs.

**Example:**


```json
{
 "include": ["message.logprobs"],
 "output": [{
 "type": "message",
 "role": "assistant",
 "content": "The capital of France is Paris.",
 "logprobs": [
 {"token": "The", "logprob": -0.0001, "top_logprobs": []},
 {"token": " capital", "logprob": -0.0005, "top_logprobs": []},
 {"token": " of", "logprob": -0.0002, "top_logprobs": []},
 {"token": " France", "logprob": -0.0003, "top_logprobs": []},
 {"token": " is", "logprob": -0.0001, "top_logprobs": []},
 {"token": " Paris", "logprob": -0.00001, "top_logprobs": [
 {"token": " Paris", "logprob": -0.00001},
 {"token": " paris", "logprob": -8.5}
 ]}
 ]
 }]
 }]
}
```

### Advanced Data

#### `reasoning.encrypted`

Include encrypted reasoning tokens for stateless multi-turn conversations.

**Use case:** When using zero data retention or `store: false`, this allows the model to continue reasoning across turns.

**Example:**


```json
{
 "include": ["reasoning.encrypted"],
 "output": [{
 "type": "reasoning",
 "encrypted_content": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
 "token_count": 150,
 "reasoning_type": "chain_of_thought"
}
```

#### `request.logs`

Include detailed request processing logs for debugging.

**Example:**


```json
{
 "include": ["request.logs"],
 "logs": {
 "request_id": "req_67ccd2bed1ec8190",
 "processing_stages": [
 {
 "stage": "input_validation",
 "duration_ms": 12,
 "status": "completed"
 },
 {
 "stage": "context_loading",
 "duration_ms": 45,
 "messages_loaded": 8
 },
 {
 "stage": "model_inference",
 "duration_ms": 2340,
 "model": "gpt-4o"
 },
 {
 "stage": "tool_execution",
 "duration_ms": 567,
 "tools_called": ["web_search"]
 }
 ],
 "total_duration_ms": 2964
 }
}
```

#### `usage`

Include basic token usage counts in the response.

**Example:**


```json
{
 "include": ["usage"],
 "usage": {
 "input_tokens": 150,
 "output_tokens": 75,
 "total_tokens": 225
 }
}
```

#### `usage.detailed`

Include detailed token usage breakdown by component.

**Example:**


```json
{
 "include": ["usage.detailed"],
 "usage": {
 "input_tokens": 150,
 "output_tokens": 75,
 "total_tokens": 225,
 "detailed": {
 "system_prompt": 20,
 "user_messages": 80,
 "thread_history": 50,
 "tool_definitions": 25,
 "assistant_output": 60,
 "tool_results": 15,
 "reasoning_tokens": 30
 },
 "cost_estimate": {
 "input_cost_usd": 0.0015,
 "output_cost_usd": 0.0015,
 "total_cost_usd": 0.0030
 }
 }
}
```

#### `rules`

Include list of rules that were passed to this response, showing rule IDs, names, and basic metadata.

**Example:**


```json
{
 "include": ["rules"],
 "rules": [
 {
 "id": "rule_abc123",
 "name": "Professional Tone",
 "category": "communication",
 "priority": 85,
 "applied": true
 },
 {
 "id": "rule_xyz789",
 "name": "Technical Documentation Style",
 "category": "formatting",
 "priority": 70,
 "applied": true
 }
 ]
}
```

#### `rules.debug`

Include detailed metadata about rule application, including which rules were considered, applied, compressed, or filtered.

**Example:**


```json
{
 "include": ["rules.debug"],
 "rules_debug": {
 "total_rules_available": 15,
 "rules_considered": 8,
 "rules_applied": 5,
 "rules_compressed": 2,
 "rules_filtered": 1,
 "application_details": [
 {
 "rule_id": "rule_abc123",
 "rule_name": "Professional Tone",
 "status": "applied",
 "priority": 85,
 "compression_ratio": 0.8,
 "tokens_used": 120
 },
 {
 "rule_id": "rule_def456",
 "rule_name": "Code Style Guide",
 "status": "filtered",
 "reason": "not_relevant_to_request",
 "priority": 60
 }
 ],
 "total_rule_tokens": 450,
 "processing_time_ms": 23
 }
}
```

## Usage Examples

### Single Include


```bash
curl https://api.aitronos.com/v1/model/response \
 -H "X-API-Key: $FREDDY_API_KEY" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "gpt-4o",
 "include": ["web_search.sources"],
 "inputs": [
 {
 "role": "user",
 "content": "What are the latest AI developments?"
 }
 ],
 "tools": {
 "webSearch": true
 }
 }'
```

### Multiple Includes


```javascript
const response = await fetch('https://api.aitronos.com/v1/model/response', {
 method: 'POST',
 headers: {
 'X-API-Key': apiKey,
 'Content-Type': 'application/json'
 },
 body: JSON.stringify({
 model: 'gpt-4o',
 include: [
 'web_search.sources',
 'usage.detailed',
 'request.logs'
 ],
 inputs: [
 { role: 'user', texts: [{ text: 'Search for AI news' }] }
 ],
 tools: { webSearch: true }
 })
});
```

### Python with All Includes


```python
import requests

response = requests.post(
 'https://api.aitronos.com/v1/model/response',
 headers={'X-API-Key': api_key},
 json={
 'model': 'gpt-4o',
 'include': [
 'web_search.sources',
 'code_interpreter.outputs',
 'file_search.results',
 'function_calls.logs',
 'message.logprobs',
 'usage.detailed',
 'request.logs'
 ],
 'inputs': [
 {'role': 'user', 'texts': [{'text': 'Comprehensive request'}]}
 ],
 'tools': {
 'webSearch': True,
 'codeInterpreter': True,
 'fileSearch': True
 }
 }
)

data = response.json()

# Access included data
if 'sources' in data['output'][0]:
 print("Web sources:", data['output'][0]['sources'])

if 'logs' in data:
 print("Processing time:", data['logs']['total_duration_ms'], "ms")

if 'detailed' in data['usage']:
 print("Token breakdown:", data['usage']['detailed'])
```

## Best Practices

### Include Only What You Need


```javascript
// Bad - includes everything unnecessarily
include: [
 'web_search.sources',
 'code_interpreter.outputs',
 'file_search.results',
 'function_calls.logs',
 'message.logprobs',
 'usage.detailed',
 'request.logs'
]

// Good - only includes what's needed
include: ['web_search.sources', 'usage.detailed']
```

### Conditional Includes


```python
def get_includes(debug_mode, show_sources):
 includes = []

 if debug_mode:
 includes.extend(['request.logs', 'usage.detailed'])

 if show_sources:
 includes.extend([
 'web_search.sources',
 'file_search.results'
 ])

 return includes

# Usage
response = send_request(
 message="Search for AI news",
 include=get_includes(debug_mode=True, show_sources=True)
)
```

### Performance Considerations


```javascript
// For production (fast, minimal)
const prodIncludes = ['web_search.sources'];

// For debugging (detailed, slower)
const debugIncludes = [
 'web_search.sources',
 'function_calls.logs',
 'request.logs',
 'usage.detailed'
];

// For analytics (comprehensive)
const analyticsIncludes = [
 'message.logprobs',
 'usage.detailed',
 'request.logs'
];

const includes = process.env.NODE_ENV === 'production'
 ? prodIncludes
 : debugIncludes;
```

## Impact on Response Size & Cost

### Response Size


```
Base response: ~2 KB

+ web_search.sources: +1-5 KB per search
+ code_interpreter.outputs: +0.5-2 KB per execution
+ file_search.results: +2-10 KB per search
+ function_calls.logs: +0.5-1 KB per call
+ message.logprobs: +50-200% of output size
+ request.logs: +1-2 KB
+ usage.detailed: +0.5 KB

Full includes: ~15-50 KB total
```

### Cost Impact

Most includes don't affect token costs (they're metadata). However:

- `message.logprobs` - No additional cost (same tokens)
- `reasoning.encrypted` - No additional cost (same tokens)
- Other includes - No token cost (pure metadata)


**Performance impact:**

- Minimal includes: +5-10ms response time
- All includes: +20-50ms response time


## Use Cases

### Customer Support with Citations


```javascript
// Show users where information came from
const response = await sendMessage({
 message: userQuery,
 include: ['web_search.sources', 'file_search.results']
});

// Display answer with sources
displayAnswer(response.output[0].text);
displaySources(response.output[0].sources);
```

### Developer Debugging


```python
# Full debugging information
response = requests.post('/v1/model/response', json={
 'model': 'gpt-4o',
 'include': [
 'function_calls.logs',
 'request.logs',
 'usage.detailed'
 ],
 'inputs': [...]
})

# Analyze performance
print(f"Total time: {response.json()['logs']['total_duration_ms']}ms")
print(f"Cost: ${response.json()['usage']['cost_estimate']['total_cost_usd']}")
```

### Analytics & Monitoring


```python
# Track token usage patterns
def log_request_analytics(response):
 usage = response['usage']['detailed']

 analytics.track('ai_request', {
 'model': response['model'],
 'total_tokens': usage['total_tokens'],
 'input_breakdown': {
 'system': usage['system_prompt'],
 'user': usage['user_messages'],
 'history': usage['thread_history']
 },
 'output_tokens': usage['assistant_output'],
 'cost_usd': usage['cost_estimate']['total_cost_usd']
 })
```

## Related Resources

- [Create Model Response](/docs/api-reference/responses/create)
- [Web Search Tool](/docs/documentation/system-tools/web-search)
- [Code Interpreter Tool](/docs/documentation/system-tools/code-interpreter)
- [File Search Tool](/docs/documentation/system-tools/file-search)
- [Function Calling](/docs/documentation/core-concepts/function-calling)