Skip to main content
result = client.spans.list(options?)
# Async
result = await client.spans.alist(options?)
Retrieve spans with optional filters and cursor-based pagination.

​
Parameters

Pass a ListSpansOptions object:
ParameterTypeRequiredDescription
prompt_slugstrNoFilter by prompt slug
status"SUCCESS" | "ERROR"NoFilter by status
start_datedatetimeNoFilter spans created after this date
end_datedatetimeNoFilter spans created before this date
user_idstrNoFilter by end user ID
session_idstrNoFilter by session ID
tagslist[str]NoFilter by tags (AND logic)
limitintNoResults per page (max 100, default 50)
cursorstrNoCursor from previous response

​
Response

class ListSpansResult(BaseModel):
    spans: list[Span]
    cursor: str | None
    has_more: bool              # alias: "hasMore"

​
Examples

​
Basic Usage

result = client.spans.list()
print(f"Found {len(result.spans)} spans")

​
Filtering by Prompt

from tracia import ListSpansOptions

result = client.spans.list(ListSpansOptions(
    prompt_slug="welcome-email",
    status="SUCCESS",
))

for span in result.spans:
    print(f"{span.span_id}: {span.latency_ms}ms, {span.total_tokens} tokens")

​
Date Range Filtering

from datetime import datetime
from tracia import ListSpansOptions

result = client.spans.list(ListSpansOptions(
    start_date=datetime(2024, 1, 1),
    end_date=datetime(2024, 1, 31),
))

​
Filtering by Tags

from tracia import ListSpansOptions

result = client.spans.list(ListSpansOptions(
    tags=["production", "v2"],  # Must have ALL tags
))

​
Pagination

from tracia import ListSpansOptions

def get_all_spans():
    all_spans = []
    cursor = None

    while True:
        result = client.spans.list(ListSpansOptions(limit=100, cursor=cursor))
        all_spans.extend(result.spans)
        if not result.has_more:
            break
        cursor = result.cursor

    return all_spans

​
Calculating Costs

from datetime import datetime
from tracia import ListSpansOptions

result = client.spans.list(ListSpansOptions(
    prompt_slug="welcome-email",
    start_date=datetime(2024, 1, 1),
))

total_cost = sum(s.cost or 0 for s in result.spans)
total_tokens = sum(s.total_tokens for s in result.spans)

print(f"Total cost: ${total_cost:.4f}")
print(f"Total tokens: {total_tokens}")

​
Error Handling

from tracia import TraciaError, TraciaErrorCode

try:
    result = client.spans.list()
except TraciaError as error:
    if error.code == TraciaErrorCode.UNAUTHORIZED:
        print("Invalid API key")