--- title: "Log Spans" method: POST path: "/projects/{project_id}/spans" tags: ["trace"] --- # Log Spans `POST /projects/{project_id}/spans` ## Path parameters - `project_id` string, uuid4, required ## Request body - LogSpansIngestRequest — Request model for ingesting spans. - `log_stream_id` string, uuid4, nullable — Log stream id associated with the traces. - `experiment_id` string, uuid4, nullable — Experiment id associated with the traces. - `metrics_testing_id` string, uuid4, nullable — Metrics testing id associated with the traces. - `logging_method` 'playground' | 'python_client' | 'typescript_client' | 'api_direct' - `client_version` string, nullable - `reliable` boolean — Whether or not to use reliable logging. If set to False, the method will respond immediately before verifying that the traces have been successfully ingested, and no error message will be returned if ingestion fails. If set to True, the method will wait for the traces to be successfully ingested or return an error message if there is an ingestion failure. - `spans` union[], required — List of spans to log. - union - AgentSpan - `type` 'agent' — Type of the trace, span or session. - `input` union — Input to the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage[] - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - union[] - union - … - `redacted_input` union — Redacted input of the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage[] - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - union[] - union - … - `output` union — Output of the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - DocumentInput[] - `page_content` string, required — Content of the document. - `metadata` object - union[] - union - … - ControlResult - `action` 'deny' | 'steer' | 'observe', required - `matched` boolean, required — Whether the control matched. False covers both non-match and error cases; use error_message to distinguish errors. - `confidence` number, nullable — Confidence score reported by the control evaluation result. - `error_message` string, nullable — Error text when control evaluation failed. This should be null for normal matches and non-matches. - `redacted_output` union — Redacted output of the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - DocumentInput[] - `page_content` string, required — Content of the document. - `metadata` object - union[] - union - … - ControlResult - `action` 'deny' | 'steer' | 'observe', required - `matched` boolean, required — Whether the control matched. False covers both non-match and error cases; use error_message to distinguish errors. - `confidence` number, nullable — Confidence score reported by the control evaluation result. - `error_message` string, nullable — Error text when control evaluation failed. This should be null for normal matches and non-matches. - `name` string — Name of the trace, span or session. - `created_at` string, date-time — Timestamp of the trace or span's creation. - `user_metadata` object — Metadata associated with this trace or span. - `tags` string[] — Tags associated with this trace or span. - `status_code` integer, nullable — Status code of the trace or span. Used for logging failure or error states. - `metrics` Metrics - `duration_ns` integer, nullable — Duration of the trace or span in nanoseconds. Displayed as 'Latency' in Galileo. - `external_id` string, nullable — A user-provided session, trace or span ID. - `dataset_input` string, nullable — Input to the dataset associated with this trace - `dataset_output` string, nullable — Output from the dataset associated with this trace - `dataset_metadata` object — Metadata from the dataset associated with this trace - `id` string, uuid4, nullable — Galileo ID of the session, trace or span - `session_id` string, uuid4, nullable — Galileo ID of the session containing the trace or span or session - `trace_id` string, uuid4, nullable — Galileo ID of the trace containing the span (or the same value as id for a trace) - `step_number` integer, nullable — Topological step number of the span. - `parent_id` string, uuid4, nullable — Galileo ID of the parent of this span - `spans` union[] — Child spans. - union - AgentSpan — recursive - WorkflowSpan - … - LlmSpan - … - RetrieverSpan - … - ToolSpan - … - ControlSpan - … - `agent_type` 'default' | 'planner' | 'react' | 'reflection' | 'router' | 'classifier' | 'supervisor' | 'judge' - `agent_name` string, nullable — Name of the agent. - WorkflowSpan - `type` 'workflow' — Type of the trace, span or session. - `input` union — Input to the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage[] - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - union[] - union - … - `redacted_input` union — Redacted input of the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage[] - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - union[] - union - … - `output` union — Output of the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - DocumentInput[] - `page_content` string, required — Content of the document. - `metadata` object - union[] - union - … - ControlResult - `action` 'deny' | 'steer' | 'observe', required - `matched` boolean, required — Whether the control matched. False covers both non-match and error cases; use error_message to distinguish errors. - `confidence` number, nullable — Confidence score reported by the control evaluation result. - `error_message` string, nullable — Error text when control evaluation failed. This should be null for normal matches and non-matches. - `redacted_output` union — Redacted output of the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - DocumentInput[] - `page_content` string, required — Content of the document. - `metadata` object - union[] - union - … - ControlResult - `action` 'deny' | 'steer' | 'observe', required - `matched` boolean, required — Whether the control matched. False covers both non-match and error cases; use error_message to distinguish errors. - `confidence` number, nullable — Confidence score reported by the control evaluation result. - `error_message` string, nullable — Error text when control evaluation failed. This should be null for normal matches and non-matches. - `name` string — Name of the trace, span or session. - `created_at` string, date-time — Timestamp of the trace or span's creation. - `user_metadata` object — Metadata associated with this trace or span. - `tags` string[] — Tags associated with this trace or span. - `status_code` integer, nullable — Status code of the trace or span. Used for logging failure or error states. - `metrics` Metrics - `duration_ns` integer, nullable — Duration of the trace or span in nanoseconds. Displayed as 'Latency' in Galileo. - `external_id` string, nullable — A user-provided session, trace or span ID. - `dataset_input` string, nullable — Input to the dataset associated with this trace - `dataset_output` string, nullable — Output from the dataset associated with this trace - `dataset_metadata` object — Metadata from the dataset associated with this trace - `id` string, uuid4, nullable — Galileo ID of the session, trace or span - `session_id` string, uuid4, nullable — Galileo ID of the session containing the trace or span or session - `trace_id` string, uuid4, nullable — Galileo ID of the trace containing the span (or the same value as id for a trace) - `step_number` integer, nullable — Topological step number of the span. - `parent_id` string, uuid4, nullable — Galileo ID of the parent of this span - `spans` union[] — Child spans. - union - AgentSpan - … - WorkflowSpan — recursive - LlmSpan - … - RetrieverSpan - … - ToolSpan - … - ControlSpan - … - LlmSpan - `type` 'llm' — Type of the trace, span or session. - `input` GalileoCoreSchemasLoggingLlmMessage[] — Input to the trace or span. - `content` union, required - string - union[] - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - `id` string, required - `function` ToolCallFunction, required - … - `redacted_input` GalileoCoreSchemasLoggingLlmMessage[], nullable — Redacted input of the trace or span. - `content` union, required - string - union[] - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - `id` string, required - `function` ToolCallFunction, required - … - `output` GalileoCoreSchemasLoggingLlmMessage - `content` union, required - string - union[] - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - `id` string, required - `function` ToolCallFunction, required - … - `redacted_output` GalileoCoreSchemasLoggingLlmMessage - `content` union, required - string - union[] - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - `id` string, required - `function` ToolCallFunction, required - … - `name` string — Name of the trace, span or session. - `created_at` string, date-time — Timestamp of the trace or span's creation. - `user_metadata` object — Metadata associated with this trace or span. - `tags` string[] — Tags associated with this trace or span. - `status_code` integer, nullable — Status code of the trace or span. Used for logging failure or error states. - `metrics` LlmMetrics - `duration_ns` integer, nullable — Duration of the trace or span in nanoseconds. Displayed as 'Latency' in Galileo. - `num_input_tokens` integer, nullable — Number of input tokens. - `num_output_tokens` integer, nullable — Number of output tokens. - `num_total_tokens` integer, nullable — Total number of tokens. - `time_to_first_token_ns` integer, nullable — Time until the first token was generated in nanoseconds. - `num_image_input_tokens` integer, nullable — Number of image input tokens. - `num_audio_input_tokens` integer, nullable — Number of audio input tokens. - `num_audio_output_tokens` integer, nullable — Number of audio output tokens. - `num_image_output_tokens` integer, nullable — Number of image output tokens. - `external_id` string, nullable — A user-provided session, trace or span ID. - `dataset_input` string, nullable — Input to the dataset associated with this trace - `dataset_output` string, nullable — Output from the dataset associated with this trace - `dataset_metadata` object — Metadata from the dataset associated with this trace - `id` string, uuid4, nullable — Galileo ID of the session, trace or span - `session_id` string, uuid4, nullable — Galileo ID of the session containing the trace or span or session - `trace_id` string, uuid4, nullable — Galileo ID of the trace containing the span (or the same value as id for a trace) - `step_number` integer, nullable — Topological step number of the span. - `parent_id` string, uuid4, nullable — Galileo ID of the parent of this span - `tools` object[], nullable — List of available tools passed to the LLM on invocation. - `events` union[], nullable — List of reasoning, internal tool call, or MCP events that occurred during the LLM span. - union - MessageEvent — An output message from the model. - … - ReasoningEvent — Internal reasoning/thinking from the model (e.g., OpenAI o1/o3 reasoning tokens). - … - InternalToolCall — A tool call executed internally by the model during reasoning. This represents internal tools like web search, code execution, file search, etc. that the model invokes (not user-defined functions or MCP tools). - … - WebSearchCallEvent — An OpenAI-style web search call event. - … - ImageGenerationEvent — An image generation event from the model. - … - MCPCallEvent — A Model Context Protocol (MCP) tool call. MCP is a protocol for connecting LLMs to external tools/data sources. This is distinct from internal tools because it involves external integrations. - … - MCPListToolsEvent — MCP list tools event - when the model queries available MCP tools. - … - MCPApprovalRequestEvent — MCP approval request - when human approval is needed for an MCP tool call. - … - `model` string, nullable — Model used for this span. - `temperature` number, nullable — Temperature used for generation. - `finish_reason` string, nullable — Reason for finishing. - RetrieverSpan - `type` 'retriever' — Type of the trace, span or session. - `input` string — Input to the trace or span. - `redacted_input` string, nullable — Redacted input of the trace or span. - `output` DocumentInput[] — Output of the trace or span. - `page_content` string, required — Content of the document. - `metadata` object - `redacted_output` DocumentInput[], nullable — Redacted output of the trace or span. - `page_content` string, required — Content of the document. - `metadata` object - `name` string — Name of the trace, span or session. - `created_at` string, date-time — Timestamp of the trace or span's creation. - `user_metadata` object — Metadata associated with this trace or span. - `tags` string[] — Tags associated with this trace or span. - `status_code` integer, nullable — Status code of the trace or span. Used for logging failure or error states. - `metrics` Metrics - `duration_ns` integer, nullable — Duration of the trace or span in nanoseconds. Displayed as 'Latency' in Galileo. - `external_id` string, nullable — A user-provided session, trace or span ID. - `dataset_input` string, nullable — Input to the dataset associated with this trace - `dataset_output` string, nullable — Output from the dataset associated with this trace - `dataset_metadata` object — Metadata from the dataset associated with this trace - `id` string, uuid4, nullable — Galileo ID of the session, trace or span - `session_id` string, uuid4, nullable — Galileo ID of the session containing the trace or span or session - `trace_id` string, uuid4, nullable — Galileo ID of the trace containing the span (or the same value as id for a trace) - `step_number` integer, nullable — Topological step number of the span. - `parent_id` string, uuid4, nullable — Galileo ID of the parent of this span - `spans` union[] — Child spans. - union - AgentSpan - … - WorkflowSpan - … - LlmSpan - … - RetrieverSpan — recursive - ToolSpan - … - ControlSpan - … - ToolSpan - `type` 'tool' — Type of the trace, span or session. - `input` string — Input to the trace or span. - `redacted_input` string, nullable — Redacted input of the trace or span. - `output` string, nullable — Output of the trace or span. - `redacted_output` string, nullable — Redacted output of the trace or span. - `name` string — Name of the trace, span or session. - `created_at` string, date-time — Timestamp of the trace or span's creation. - `user_metadata` object — Metadata associated with this trace or span. - `tags` string[] — Tags associated with this trace or span. - `status_code` integer, nullable — Status code of the trace or span. Used for logging failure or error states. - `metrics` Metrics - `duration_ns` integer, nullable — Duration of the trace or span in nanoseconds. Displayed as 'Latency' in Galileo. - `external_id` string, nullable — A user-provided session, trace or span ID. - `dataset_input` string, nullable — Input to the dataset associated with this trace - `dataset_output` string, nullable — Output from the dataset associated with this trace - `dataset_metadata` object — Metadata from the dataset associated with this trace - `id` string, uuid4, nullable — Galileo ID of the session, trace or span - `session_id` string, uuid4, nullable — Galileo ID of the session containing the trace or span or session - `trace_id` string, uuid4, nullable — Galileo ID of the trace containing the span (or the same value as id for a trace) - `step_number` integer, nullable — Topological step number of the span. - `parent_id` string, uuid4, nullable — Galileo ID of the parent of this span - `spans` union[] — Child spans. - union - AgentSpan - … - WorkflowSpan - … - LlmSpan - … - RetrieverSpan - … - ToolSpan — recursive - ControlSpan - … - `tool_call_id` string, nullable — ID of the tool call. - ControlSpan - `type` 'control' — Type of the trace, span or session. - `input` union — Input to the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage[] - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - union[] - union - … - `redacted_input` union — Redacted input of the trace or span. - string - GalileoCoreSchemasLoggingLlmMessage[] - `content` union, required - … - `role` 'agent' | 'assistant' | 'developer' | 'function' | 'system' | 'tool' | 'user', required - `tool_call_id` string, nullable - `tool_calls` ToolCall[], nullable - … - union[] - union - … - `output` ControlResult - `action` 'deny' | 'steer' | 'observe', required - `matched` boolean, required — Whether the control matched. False covers both non-match and error cases; use error_message to distinguish errors. - `confidence` number, nullable — Confidence score reported by the control evaluation result. - `error_message` string, nullable — Error text when control evaluation failed. This should be null for normal matches and non-matches. - `redacted_output` ControlResult - `action` 'deny' | 'steer' | 'observe', required - `matched` boolean, required — Whether the control matched. False covers both non-match and error cases; use error_message to distinguish errors. - `confidence` number, nullable — Confidence score reported by the control evaluation result. - `error_message` string, nullable — Error text when control evaluation failed. This should be null for normal matches and non-matches. - `name` string — Name of the trace, span or session. - `created_at` string, date-time — Timestamp of the trace or span's creation. - `user_metadata` object — Metadata associated with this trace or span. - `tags` string[] — Tags associated with this trace or span. - `status_code` integer, nullable — Status code of the trace or span. Used for logging failure or error states. - `metrics` Metrics - `duration_ns` integer, nullable — Duration of the trace or span in nanoseconds. Displayed as 'Latency' in Galileo. - `external_id` string, nullable — A user-provided session, trace or span ID. - `dataset_input` string, nullable — Input to the dataset associated with this trace - `dataset_output` string, nullable — Output from the dataset associated with this trace - `dataset_metadata` object — Metadata from the dataset associated with this trace - `id` string, uuid4, nullable — Galileo ID of the session, trace or span - `session_id` string, uuid4, nullable — Galileo ID of the session containing the trace or span or session - `trace_id` string, uuid4, nullable — Galileo ID of the trace containing the span (or the same value as id for a trace) - `step_number` integer, nullable — Topological step number of the span. - `parent_id` string, uuid4, nullable — Galileo ID of the parent of this span - `control_id` integer, nullable — Identifier of the control definition that produced this span. - `agent_name` string, nullable — Normalized agent name associated with this control execution. - `check_stage` 'pre' | 'post' - `applies_to` 'llm_call' | 'tool_call' - `evaluator_name` string, nullable — Representative evaluator name for this control span. For composite controls, this is the primary evaluator chosen for observability identity. - `selector_path` string, nullable — Representative selector path for this control span. For composite controls, this is the primary selector path chosen for observability identity. - `trace_id` string, uuid4, required — Trace id associated with the spans. - `parent_id` string, uuid4, required — Parent trace or span id. ## Response `200` Successful Response - LogSpansIngestResponse - `log_stream_id` string, uuid4, nullable — Log stream id associated with the traces. - `experiment_id` string, uuid4, nullable — Experiment id associated with the traces. - `metrics_testing_id` string, uuid4, nullable — Metrics testing id associated with the traces. - `project_id` string, uuid4, required — Project id associated with the traces. - `project_name` string, required — Project name associated with the traces. - `session_id` string, uuid4, nullable — Session id associated with the traces. - `records_count` integer, required — Total number of records ingested - `trace_id` string, uuid4, required — Trace id associated with the spans. - `parent_id` string, uuid4, required — Parent trace or span id. ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/galileo/apis/galileo-api-server.md) · [All operations](https://skmtc.net/galileo/apis/galileo-api-server/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/galileo/galileo-api-server/versions/933e8c8e6366/schema)