# Create waterfall URL: https://docs.hanzo.ai/docs/openapi/o11y/getwaterfallv4 > Returns a trace's waterfall: every span when the trace is small enough, a capped window around the selected span when it is not, with the uncollapsed subtrees the caller asked to keep open. `POST /v1/o11y/traces/{traceId}/waterfall` > [O11y →](https://docs.hanzo.ai/docs/openapi/o11y) · [All API references →](https://docs.hanzo.ai/docs/openapi) · [Get started →](https://docs.hanzo.ai/docs/guides) | | | | ------------- | --------------------------------------------------------- | | **Address** | `https://api.hanzo.ai/v1/o11y/traces/{traceId}/waterfall` | | **Method** | `POST` | | **Operation** | `GetWaterfallV4` | | **Auth** | `Authorization: Bearer $HANZO_API_KEY` | Returns a trace's waterfall: every span when the trace is small enough, a capped window around the selected span when it is not, with the uncollapsed subtrees the caller asked to keep open. Callers need the viewer role; the runtime's own gate enforces it. ## Request 3 fields, body `application/json` (required). | Field | In | Type | Required | Description | | ------------------ | ---- | --------- | -------- | ----------- | | `traceId` | path | string | yes | | | `selectedSpanId` | body | string | — | | | `uncollapsedSpans` | body | string\[] | — | | ## Response | Status | Body | Meaning | | --------- | -------------------------- | ----------------- | | `200` | o11y.O11yTraceWaterfallOut | ok | | `202` | Approval | held for approval | | `default` | problem-details | refused | `200` body — 51 fields. | Field | In | Type | Always | Description | | -------------------------------------- | ---- | --------------------------- | ------ | ------------------------------------------------------ | | `data` | body | o11y.GettableWaterfallTrace | — | | | `data.endTimestampMillis` | body | integer (uint64) | — | | | `data.hasMissingSpans` | body | boolean | — | | | `data.hasMore` | body | boolean | — | | | `data.rootServiceEntryPoint` | body | string | — | | | `data.rootServiceName` | body | string | — | | | `data.spans` | body | o11y.WaterfallSpan\[] | — | | | `data.spans[].attributes` | body | object | — | | | `data.spans[].attributes.*` | body | any | — | | | `data.spans[].db_name` | body | string | — | Calculated fields, derived from the span's attributes. | | `data.spans[].db_operation` | body | string | — | | | `data.spans[].duration_nano` | body | integer (uint64) | — | | | `data.spans[].events` | body | o11y.Event\[] | — | | | `data.spans[].events[].attributeMap` | body | object | — | | | `data.spans[].events[].attributeMap.*` | body | any | — | | | `data.spans[].events[].isError` | body | boolean | — | | | `data.spans[].events[].name` | body | string | — | | | `data.spans[].events[].timeUnixNano` | body | integer (uint64) | — | | | `data.spans[].external_http_method` | body | string | — | | | `data.spans[].external_http_url` | body | string | — | | | `data.spans[].flags` | body | integer (uint32) | — | | | `data.spans[].has_children` | body | boolean | — | | | `data.spans[].has_error` | body | boolean | — | | | `data.spans[].http_host` | body | string | — | | | `data.spans[].http_method` | body | string | — | | | `data.spans[].http_url` | body | string | — | | | `data.spans[].is_remote` | body | string | — | | | `data.spans[].kind_string` | body | string | — | | | `data.spans[].level` | body | integer (uint64) | — | | | `data.spans[].name` | body | string | — | | | `data.spans[].parent_span_id` | body | string | — | | | `data.spans[].references` | body | o11y.OtelSpanRef\[] | — | | | `data.spans[].references[].refType` | body | string | — | | | `data.spans[].references[].spanId` | body | string | — | | | `data.spans[].references[].traceId` | body | string | — | | | `data.spans[].resource` | body | object | — | | | `data.spans[].resource.*` | body | string | — | | | `data.spans[].response_status_code` | body | string | — | | | `data.spans[].span_id` | body | string | — | | | `data.spans[].status_code` | body | integer (int16) | — | | | `data.spans[].status_code_string` | body | string | — | | | `data.spans[].status_message` | body | string | — | | | `data.spans[].sub_tree_node_count` | body | integer (uint64) | — | | | `data.spans[].time_unix` | body | integer (uint64) | — | | | `data.spans[].trace_id` | body | string | — | | | `data.spans[].trace_state` | body | string | — | | | `data.startTimestampMillis` | body | integer (uint64) | — | | | `data.totalErrorSpansCount` | body | integer (uint64) | — | | | `data.totalSpansCount` | body | integer (uint64) | — | | | `data.uncollapsedSpans` | body | string\[] | — | | | `status` | body | string | — | Status is "success". | Failure carries the platform error shape — see [Errors](https://docs.hanzo.ai/docs/errors). ## Examples **CLI** ```bash hanzo o11y traces waterfall ``` **SDK** **.ts** ```ts import { Configuration, O11yApi } from 'hanzoai'; const api = new O11yApi(new Configuration({ accessToken: process.env.HANZO_API_KEY })); const { data } = await api.getWaterfallV4({ traceId: 'traceId', selectedSpanId: "", uncollapsedSpans: [""] }); ``` **.py** ```python from hanzoai.cloud import ApiClient, Configuration from hanzoai.cloud.api import O11yApi client = ApiClient(Configuration(access_token=os.environ["HANZO_API_KEY"])) result = O11yApi(client).get_waterfall_v4(trace_id='traceId', selected_span_id="", uncollapsed_spans=[""]) ``` **.go** ```go cfg := hanzoai.NewConfiguration() cfg.AddDefaultHeader("Authorization", "Bearer "+os.Getenv("HANZO_API_KEY")) client := hanzoai.NewAPIClient(cfg) resp, _, err := client.O11yAPI.GetWaterfallV4(context.Background()).Execute() if err != nil { return err } ``` **.rs** ```rust use hanzo_client::apis::{configuration::Configuration, o11y_api}; let mut cfg = Configuration::new(); cfg.bearer_access_token = std::env::var("HANZO_API_KEY").ok(); let result = o11y_api::get_waterfall_v4(&cfg, Default::default()).await?; ``` **.java** ```java import ai.hanzo.cloud.ApiClient; import ai.hanzo.cloud.api.O11yApi; ApiClient client = new ApiClient(); client.setBearerToken(System.getenv("HANZO_API_KEY")); var result = new O11yApi(client).getWaterfallV4(); ``` **HTTP** ```bash curl -X POST https://api.hanzo.ai/v1/o11y/traces//waterfall \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "selectedSpanId": "", "uncollapsedSpans": [ "" ] }' ``` **MCP** Tool `o11y`, op `GetWaterfallV4` — POST the JSON-RPC envelope to `https://api.hanzo.ai/v1/mcp`. ```bash curl -X POST https://api.hanzo.ai/v1/mcp \ -H "Authorization: Bearer $HANZO_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": { "name": "o11y", "arguments": { "op": "GetWaterfallV4", "input": { "traceId": "", "selectedSpanId": "", "uncollapsedSpans": [ "" ] } } } }' ``` --- [O11y API](https://docs.hanzo.ai/docs/openapi/o11y) · [All Hanzo APIs](https://docs.hanzo.ai/docs/openapi) · [Interactive reference](https://docs.hanzo.ai/docs/openapi/reference)