> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runcascade.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK Reference

> Complete reference for the more in depth Cascade Python SDK

## Convenience functions

These top-level functions let you interact with Cascade without creating a client:

```python theme={null}
from cascade import list_projects, list_traces, get_trace, get_trace_tree
```

### List projects

```python theme={null}
# List all projects in your organization
projects = list_projects()
```

### List traces

```python theme={null}
# 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

```python theme={null}
# 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:

```python theme={null}
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 |