Skip to content
Last updated

Response Includes

🔨 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:

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

With include:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{
  "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

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

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

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

// ❌ 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

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

// 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

// 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

# 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

# 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']
    })
Previous page
Next page