Span types | Respan Docs

Set up Respan

Sign up — Create an account at platform.respan.ai
Create an API key — Generate one on the API keys page
Add credits or a provider key — Add credits on the Credits page or connect your own provider key on the Integrations page

Use AI

Add the Docs MCP to your AI coding tool to get help building with Respan. No API key needed.

1 {
2   "mcpServers": {
3     "respan-docs": {
4       "url": "https://mcp.respan.ai/mcp/docs"
5     }
6   }
7 }

Overview

Every span has a log_type field that determines its input/output format. The most common type is chat, but Respan supports logging embeddings, audio, tool calls, and workflow spans.

All span types use universal input and output fields and are sent to the same logging endpoint. For the complete field reference, see Span fields & parameters.

All span types

LLM inference

Workflow & agent

Other

Span type	Description	Input	Output
`chat`	Chat completions (default)	Messages array	Assistant message
`completion`	Legacy completion format	Prompt string	Completion string
`response`	Response API calls	Request object	Response object
`embedding`	Vector embeddings	Text string	Embeddings array
`transcription`	Speech-to-text	Audio metadata	Transcribed text
`speech`	Text-to-speech	Text string	Audio metadata

Chat

The default span type. Input is an array of messages, output is the assistant’s response.

1 {
2   "model": "gpt-4o",
3   "input": [
4     {"role": "system", "content": "You are a helpful assistant."},
5     {"role": "user", "content": "What is machine learning?"}
6   ],
7   "output": {
8     "role": "assistant",
9     "content": "Machine learning is a subset of artificial intelligence..."
10   }
11 }

Images

Include images in your messages using the image_url content type. This follows the same format as the OpenAI vision API.

1 {
2   "model": "gpt-4-vision-preview",
3   "input": [
4     {
5       "role": "user",
6       "content": [
7         {
8           "type": "text",
9           "text": "What do you see in this image?"
10         },
11         {
12           "type": "image_url",
13           "image_url": {
14             "url": "https://example.com/image.png",
15             "detail": "auto"
16           }
17         }
18       ]
19     }
20   ],
21   "output": {
22     "role": "assistant",
23     "content": "This image shows..."
24   }
25 }

The detail parameter can be auto, low, or high.

Videos

Include videos in your messages using the video_url content type. Supported formats: mp4, mov, wmv, avi.

1 {
2   "model": "gpt-5.4",
3   "input": [
4     {
5       "role": "user",
6       "content": [
7         {
8           "type": "text",
9           "text": "What happens in this video?"
10         },
11         {
12           "type": "video_url",
13           "video_url": {
14             "url": "https://example.com/video.mp4"
15           }
16         }
17       ]
18     }
19   ],
20   "output": {
21     "role": "assistant",
22     "content": "The video shows..."
23   }
24 }

Videos are rendered in Logs, Playground, Prompts, and Experiments.

Thinking blocks

When using models with thinking capabilities (e.g. Claude with extended thinking), the response includes additional reasoning fields that are automatically captured.

Request:

1 {
2   "model": "claude-sonnet-4-20250514",
3   "max_tokens": 16000,
4   "thinking": {
5     "type": "enabled",
6     "budget_tokens": 10000
7   },
8   "messages": [
9     {"role": "user", "content": "Prove there are infinitely many primes p where p mod 4 = 3."}
10   ]
11 }

Response fields:

1 {
2   "role": "assistant",
3   "content": "Yes, there are infinitely many such primes...",
4   "reasoning_content": "This is asking about primes congruent to 3 modulo 4...",
5   "thinking_blocks": [
6     {
7       "type": "thinking",
8       "thinking": "This is asking about primes congruent to 3 modulo 4...",
9       "signature": "EswgCkYIBhgCKkDCG..."
10     }
11   ]
12 }

For more on enabling thinking mode via the gateway, see Enable Thinking.

Prompt variables

Pass prompt variables so they appear in the side panel for easy inspection and can be added to testsets with one click.

Wrap variables in {{}} in your input and pass a variables object:

1 "input": [
2     {
3       "content": "Please develop an optimized Python function to {{task_description}}, utilizing {{specific_library}}.",
4       "role": "user"
5     }
6 ],
7 "variables": {
8     "task_description": "Square a number",
9     "specific_library": "math"
10 }

If you are using prompts via the LLM Gateway, variables are logged automatically — no need to pass them manually.

Tool calls

Record tool calls and function calling interactions as part of chat messages:

1 import requests
2 
3 url = "https://api.respan.ai/api/request-logs/"
4 headers = {
5     "Authorization": "Bearer YOUR_RESPAN_API_KEY",
6     "Content-Type": "application/json"
7 }
8 
9 payload = {
10     "model": "gpt-4",
11     "input": [
12         {"role": "user", "content": "What's the weather in Boston?"},
13         {
14             "role": "assistant",
15             "content": None,
16             "tool_calls": [
17                 {
18                     "id": "call_abc123",
19                     "type": "function",
20                     "function": {
21                         "name": "get_current_weather",
22                         "arguments": '{"location": "Boston, MA"}'
23                     }
24                 }
25             ]
26         }
27     ],
28     "output": {
29         "role": "assistant",
30         "content": "The current weather in Boston is 72°F and sunny."
31     },
32     "tools": [
33         {
34             "type": "function",
35             "function": {
36                 "name": "get_current_weather",
37                 "description": "Get the current weather in a given location",
38                 "parameters": {
39                     "type": "object",
40                     "properties": {
41                         "location": {"type": "string", "description": "City and state, e.g. San Francisco, CA"},
42                         "unit": {"type": "string", "enum": ["celsius", "fahrenheit"]}
43                     },
44                     "required": ["location"]
45                 }
46             }
47         }
48     ]
49 }
50 
51 response = requests.post(url, headers=headers, json=payload)

Key fields:

tool_calls in the assistant message — array of function calls made
tools at the top level — array of available function definitions
tool_choice (optional) — specify which tool the model should use

Embedding

Set log_type to "embedding". Input is text, output is the vector array.

1 import requests
2 
3 url = "https://api.respan.ai/api/request-logs/"
4 headers = {
5     "Authorization": "Bearer YOUR_RESPAN_API_KEY",
6     "Content-Type": "application/json"
7 }
8 payload = {
9     "log_type": "embedding",
10     "model": "text-embedding-3-small",
11     "input": "something to embed",
12     "output": [
13         -0.006929283495992422,
14         -0.005336422007530928,
15         -4.547132266452536e-05,
16         -0.024047505110502243
17     ],
18     "latency": 0.323887338
19 }
20 response = requests.post(url, headers=headers, json=payload)

Speech & transcription

Transcription (speech-to-text)

Set log_type to "transcription". Input is audio metadata, output is transcribed text.

1 {
2   "log_type": "transcription",
3   "model": "whisper-1",
4   "input": {"audio_url": "https://example.com/audio.mp3", "filename": "recording.mp3"},
5   "output": "Hello, how can I help you today?"
6 }

Speech (text-to-speech)

Set log_type to "speech". Input is text, output is audio metadata.

1 {
2   "log_type": "speech",
3   "model": "tts-1",
4   "input": "Hello, how can I help you today?",
5   "output": {"audio_url": "https://example.com/output.mp3", "filename": "response.mp3"}
6 }

Workflow & agent types

These span types are used by tracing to represent spans in a trace hierarchy:

workflow — Root-level workflow orchestration
task — Individual task within a workflow
tool — Tool or function execution
agent — AI agent operation
handoff — Agent-to-agent transfer
guardrail — Safety and validation check

For details on how to create and orchestrate these span types, see Tracing SDK.