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
TheCascadeEval 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
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
list_failures(project) | List evaluation failures |
get_failure_stats(project) | Get aggregate failure statistics |
Traces and projects
| Method | Description |
|---|---|
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
| Method | Description |
|---|---|
resolve_scorer_names(names) | Resolve short names to scorer UUIDs |
generate_scorer_from_comment(...) | Auto-generate a scorer from feedback |