# Response Includes

div
strong
🔨 In Development
 — This section is still being developed and may change.


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
    }
  }]
}
```

#### `computer_use.screenshots`

Include screenshot URLs from computer interaction tool calls.

**Example:**


```json
{
  "include": ["computer_use.screenshots"],
  "output": [{
    "type": "tool_call",
    "tool_name": "computer_use",
    "action": "click",
    "screenshot": {
      "before": "https://cdn.freddy.aitronos.com/screenshots/before_abc123.png",
      "after": "https://cdn.freddy.aitronos.com/screenshots/after_abc123.png",
      "timestamp": "2025-01-06T10:30:45Z"
    }
  }]
}
```

#### `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",
    "texts": [{"text": "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",
    "texts": [{"text": "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",
    "texts": [{
      "text": "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-4.1"
      },
      {
        "stage": "tool_execution",
        "duration_ms": 567,
        "tools_called": ["web_search"]
      }
    ],
    "total_duration_ms": 2964
  }
}
```

#### `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
    }
  }
}
```

## Usage Examples

### Single Include


```bash
curl https://api.freddy.aitronos.com/v1/model/response \
  -H "Authorization: Bearer $FREDDY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4.1",
    "include": ["web_search.sources"],
    "inputs": [
      {
        "role": "user",
        "texts": [{"text": "What are the latest AI developments?"}]
      }
    ],
    "tools": {
      "webSearch": true
    }
  }'
```

### Multiple Includes


```javascript
const response = await fetch('https://api.freddy.aitronos.com/v1/model/response', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${apiKey}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    model: 'gpt-4.1',
    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.freddy.aitronos.com/v1/model/response',
    headers={'Authorization': f'Bearer {api_key}'},
    json={
        'model': 'gpt-4.1',
        '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-4.1',
    '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)