---

title: "trace" sidebar_label: "trace" pagination_prev: null pagination_next: null

Provides a user-friendly trace stack into an operation that occurred in Spice. This command retrieves and displays task execution traces from the runtime.task_history table.

Usage

task - The name of the task whose trace is requested. Supported tasks include:

• accelerated_refresh
• ai_chat
• ai_completion
• sql_query
• nsql
• tool_use::document_similarity
• tool_use::list_datasets
• tool_use::sql
• tool_use::table_schema
• tool_use::sample_data
• tool_use::sql_query
• tool_use::memory
• vector_search
• scheduled_worker

These tasks are from the task column in the Spice SQL runtime.task_history table.

Flags

• --trace-id Retrieve the trace with the given trace ID (the column trace_id from runtime.task_history).
• --id Retrieve the trace with the given id label (i.e. the task has a valid id within the labels column of runtime.task_history).
• --api-key Specify the API key for authentication.
• --include-output: Include, as an additional column, the captured output to each span (i.e. the captured_output column from runtime.task_history). Note: If captured outputs are not being stored, this will return an empty row.
• --include-input: Include, as an additional column, the input to each span (i.e. the input column from runtime.task_history).

The latest trace for the task will be used if neither --trace-id nor --id is specified.

Examples

Retrieve the trace for the last text-to-SQL operation

Retrieve the trace for a specific task by ID

Retrieve a trace by trace-id

Output Example

This output represents a structured trace of executed tasks.

Output Example (with --include-output)