Skip to main content

​
Convenience functions

These top-level functions let you interact with Cascade without creating a client: 
from cascade import list_projects, list_traces, get_trace, get_trace_tree

​
List projects

# List all projects in your organization
projects = list_projects()

​
List traces

# List recent traces for a project
resp = list_traces("travel_agent", days=7, limit=20)
for t in resp["traces"]:
    print(f"{t['trace_id'][:12]}  {t['root_span_name']}  {t['status']}")

​
Get trace details

# Get all spans for a trace
data = get_trace("abc123...")
for span in data["spans"]:
    print(f"  {span['name']}  {span['span_id']}")

# Get the trace as a hierarchical tree (same view as the dashboard)
tree = get_trace_tree("abc123...")

​
CascadeEval client

The CascadeEval class provides full programmatic access to the evaluation API: 
from cascade import CascadeEval

evals = CascadeEval(
    endpoint="https://api.runcascade.com",  # optional, auto-detected
    api_key="csk_live_...",                  # optional, reads CASCADE_API_KEY
)

​
Scorers

MethodDescription
list_scorers()List all scorers for your org
get_scorer(scorer_id)Get a scorer by ID
create_scorer(...)Create a new scorer
update_scorer(scorer_id, ...)Update scorer fields
delete_scorer(scorer_id)Delete a scorer
list_builtin_scorers()List built-in scorer templates
get_builtin_scorer(key)Get a built-in template by key

​
Evaluation

MethodDescription
evaluate(trace_id, scorer_ids)Run scorers against a trace
evaluate_spans(trace_id, scorer_ids)Run span-level scorers on matching spans
list_results(...)List evaluation results with filters
get_result(result_id)Get a single evaluation result
delete_result(result_id)Delete an evaluation result

​
Tasks

MethodDescription
create_task(name, mode, scorer_ids)Create a batch or scheduled task
list_tasks(...)List evaluation tasks
get_task(task_id)Get a task by ID
update_task(task_id, ...)Update task fields
delete_task(task_id)Delete a task
run_task(task_id)Trigger a batch task
pause_task(task_id)Pause a scheduled task
resume_task(task_id)Resume a paused task
get_task_results(task_id)Get results for a task

​
Failures

MethodDescription
list_failures(project)List evaluation failures
get_failure_stats(project)Get aggregate failure statistics

​
Traces and projects

MethodDescription
list_projects()List all projects
list_traces(project)List traces with filtering
get_trace(trace_id)Get all spans for a trace
get_trace_tree(trace_id)Get trace as a hierarchical tree
get_span(span_id)Get a single span
get_spans_since(trace_id, since_time)Get spans added after a timestamp

​
Other

MethodDescription
resolve_scorer_names(names)Resolve short names to scorer UUIDs
generate_scorer_from_comment(...)Auto-generate a scorer from feedback