Response Schemas

This page documents all response schemas returned by the Dedalus API. All responses follow OpenAI-compatible formats.

Dedalus Runner

object

Response object returned by the DedalusRunner for non-streaming tool execution runs.

Show Properties

string

required

Final text output from the conversation after all tool executions complete

array

required

List of all tool execution results from the run

Show Tool Result Properties

string

Name of the tool that was executed

any

The result returned by the tool execution

integer

The step number when this tool was executed

string

Error message if the tool execution failed

integer

required

Total number of steps (LLM calls) used during the run

array

required

List of tool names that were called during the run

array

required

Full conversation history including system prompts, user messages, assistant responses, and tool calls/results. Useful for debugging, logging, or continuing conversations.

array

Optional list of detected intents (when return_intent=true)

string

Alias for final_output (legacy compatibility)

string

Alias for final_output (legacy compatibility)

Show Methods

method

Returns a copy of the full conversation history (messages) for use in follow-up runs. Enables multi-turn conversations by passing the result to subsequent runner.run() calls.

Example

from dedalus_labs import Dedalus, DedalusRunner

client = Dedalus(api_key="YOUR_API_KEY")
runner = DedalusRunner(client)

def get_weather(location: str) -> str:
    """Get the current weather for a location."""
    return f"The weather in {location} is sunny and 72°F"

result = runner.run(
    input="What's the weather like in San Francisco?",
    tools=[get_weather],
    model="openai/gpt-5-nano",
    max_steps=5
)

# Access result properties
print(result.final_output)   # "The weather in San Francisco is sunny and 72°F"
print(result.steps_used)     # e.g., 2
print(result.tools_called)   # ["get_weather"]
print(result.tool_results)   # [{"name": "get_weather", "result": "The weather...", "step": 1}]

Accessing Message History

import json

# Print the full conversation history
for msg in result.messages:
    role = msg.get("role")
    content = msg.get("content", "")

    if role == "user":
        print(f"User: {content}")
    elif role == "assistant":
        if msg.get("tool_calls"):
            tools = [tc["function"]["name"] for tc in msg["tool_calls"]]
            print(f"Assistant: [calling {', '.join(tools)}]")
        else:
            print(f"Assistant: {content}")
    elif role == "tool":
        print(f"Tool Result: {content[:100]}...")

# Store message history to JSON for logging/debugging
with open("conversation_log.json", "w") as f:
    json.dump(result.messages, f, indent=2)

# Continue the conversation with message history
follow_up = runner.run(
    messages=result.to_input_list(),  # Pass previous conversation
    input="What about New York?",      # Add new user message
    tools=[get_weather],
    model="openai/gpt-5-nano"
)

Example Response

{
	"final_output": "The weather in San Francisco is sunny and 72°F",
	"tool_results": [
		{
			"name": "get_weather",
			"result": "The weather in San Francisco is sunny and 72°F",
			"step": 1
		}
	],
	"steps_used": 2,
	"tools_called": ["get_weather"],
	"messages": [
		{ "role": "user", "content": "What's the weather like in San Francisco?" },
		{
			"role": "assistant",
			"tool_calls": [
				{
					"id": "call_abc123",
					"type": "function",
					"function": {
						"name": "get_weather",
						"arguments": "{\"location\": \"San Francisco\"}"
					}
				}
			]
		},
		{
			"role": "tool",
			"tool_call_id": "call_abc123",
			"content": "The weather in San Francisco is sunny and 72°F"
		},
		{
			"role": "assistant",
			"content": "The weather in San Francisco is sunny and 72°F"
		}
	],
	"intents": null
}

Chat Completions

object

The complete response object for non-streaming chat completions.

Show Properties

string

required

Unique identifier for the chat completion

string

required

Object type, always chat.completion

integer

required

Unix timestamp (seconds) when the completion was created

string

required

The model used for completion (e.g., openai/gpt-5-nano)

array

required

List of completion choices

Show Choice Properties

integer

Index of this choice

object

The generated message

Show Message Properties

string

Role of the message author (assistant, tool, etc.)

string

The content of the message

array

Tool calls requested by the model (present when finish_reason is tool_calls)

Show Tool Call Properties

string

Unique identifier for this tool call, referenced when returning results via tool_call_id

string

Always function

object

Show Function Properties

string

Name of the function the model wants to invoke

string

JSON-encoded string of the arguments. Must be parsed with JSON.parse / json.loads before use.

string

Why the generation stopped: stop, length, tool_calls, content_filter

object

Log probability information for tokens

object

required

Token usage statistics

Show Usage Properties

integer

Number of tokens in the prompt

integer

Number of tokens in the completion

integer

Total tokens used (prompt + completion)

string

System fingerprint for reproducibility

Example

{
	"id": "chatcmpl-abc123",
	"object": "chat.completion",
	"created": 1677652288,
	"model": "openai/gpt-5-nano",
	"choices": [
		{
			"index": 0,
			"message": {
				"role": "assistant",
				"content": "Hello! I'm doing well, thank you for asking."
			},
			"finish_reason": "stop"
		}
	],
	"usage": {
		"prompt_tokens": 13,
		"completion_tokens": 12,
		"total_tokens": 25
	}
}

object

Streamed response chunks for streaming completions (stream=true).

Show Properties

string

required

Unique identifier for the chat completion

string

required

Object type, always chat.completion.chunk

integer

required

Unix timestamp when the chunk was created

string

required

The model being used

array

required

List of chunk choices

Show Choice Properties

integer

Index of this choice

object

Incremental content delta

Show Delta Properties

string

Role (only in first chunk)

string

Incremental content string

array

Incremental tool call updates

string

Reason for completion (only in final chunk): stop, length, tool_calls, content_filter, or null

Example

{
	"id": "chatcmpl-abc123",
	"object": "chat.completion.chunk",
	"created": 1677652288,
	"model": "openai/gpt-5-nano",
	"choices": [
		{
			"index": 0,
			"delta": {
				"content": "Hello"
			},
			"finish_reason": null
		}
	]
}

Embeddings

object

Response object for embedding creation requests.

Show Properties

string

required

Object type, always list

array

required

List of embedding objects

Show Embedding Properties

string

Object type, always embedding

array

The embedding vector (array of floats)

integer

Index of this embedding

string

required

The model used to generate embeddings

object

required

Token usage information

Show Usage Properties

integer

Number of tokens in the input

integer

Total tokens processed

Example

{
	"object": "list",
	"data": [
		{
			"object": "embedding",
			"embedding": [0.0023064255, -0.009327292, -0.0028842222],
			"index": 0
		}
	],
	"model": "openai/text-embedding-3-small",
	"usage": {
		"prompt_tokens": 8,
		"total_tokens": 8
	}
}

Models

object

Response object for listing available models. Includes rich metadata about capabilities and routing.

Show Properties

string

required

Object type, always list

array

required

List of model objects

Show Model Properties

string

Model identifier with provider prefix (e.g., openai/gpt-4o, anthropic/claude-opus-4-5)

string

Provider name: openai, anthropic, google, xai, deepseek, mistral, etc.

string

ISO 8601 timestamp when the model was created

string

Human-readable display name (optional)

string

Model description (optional)

object

Model capabilities

Show Capabilities

boolean

Supports text generation via chat completions

boolean

Supports image input / multimodal

boolean

Can generate images

boolean

Supports audio input/output

boolean

Supports tool/function calling

boolean

Supports structured JSON output

boolean

Supports streaming responses

boolean

Supports extended reasoning (e.g., o1, o3, Claude thinking)

integer

Maximum input context window in tokens

integer

Maximum output tokens

object

Provider-specific metadata

Show Provider Info

string

Model status: enabled, disabled, preview, deprecated

string

Which upstream API this model uses (e.g., openai/chat/completions, anthropic/messages)

Example

{
	"object": "list",
	"data": [
		{
			"id": "openai/gpt-4o",
			"provider": "openai",
			"created_at": "1970-01-01T00:00:00Z",
			"display_name": null,
			"description": null,
			"capabilities": {
				"text": true,
				"vision": null,
				"image_generation": null,
				"audio": null,
				"tools": null,
				"structured_output": null,
				"streaming": null,
				"thinking": null,
				"input_token_limit": null,
				"output_token_limit": null
			},
			"provider_info": {
				"status": "enabled",
				"upstream_api": "openai/chat/completions"
			}
		},
		{
			"id": "openai/o1",
			"provider": "openai",
			"created_at": "1970-01-01T00:00:00Z",
			"capabilities": {
				"text": true,
				"thinking": true
			},
			"provider_info": {
				"status": "enabled",
				"upstream_api": "openai/chat/completions"
			}
		},
		{
			"id": "anthropic/claude-opus-4-5",
			"provider": "anthropic",
			"created_at": "1970-01-01T00:00:00Z",
			"capabilities": {
				"text": true,
				"vision": true,
				"tools": true
			},
			"provider_info": {
				"status": "enabled",
				"upstream_api": "anthropic/messages"
			}
		}
	]
}

Images

object

Response object for image generation requests.

Show Properties

integer

required

Unix timestamp when the images were generated

array

required

List of generated image objects

Show Image Properties

string

URL of the generated image (when response_format="url")

string

Base64-encoded image data (when response_format="b64_json")

string

The revised prompt used to generate the image (may differ from input for safety)

Example

{
	"created": 1677652288,
	"data": [
		{
			"url": "https://images.example.com/abc123.png",
			"revised_prompt": "A cute baby sea otter floating on its back in calm blue water"
		}
	]
}

Audio

object

Response object for audio transcription requests.

Show Properties

string

required

The transcribed text from the audio file

Example

{
	"text": "Hello, this is a test of audio transcription."
}

object

Response object for audio translation requests (always translates to English).

Show Properties

string

required

The translated text from the audio file (in English)

Example

{
	"text": "Hello, this is a test of audio translation."
}

Errors

object

All endpoints may return errors with this structure.

Show Properties

object

required

Error information object

Show Error Properties

string

Human-readable error message

string

Error type: invalid_request_error, authentication_error, rate_limit_error, server_error

string

Specific error code for programmatic handling

string

Parameter that caused the error (if applicable)

Example

{
	"error": {
		"message": "Invalid API key provided",
		"type": "authentication_error",
		"code": "invalid_api_key"
	}
}

Overview

Endpoints

Guides

Dedalus Runner

Chat Completions

Embeddings

Models

Images

Audio

Errors

​Dedalus Runner

​Chat Completions

​Embeddings

​Models

​Images

​Audio

​Errors

Dedalus Runner

Chat Completions

Embeddings

Models

Images

Audio

Errors