> For the complete documentation index, see [llms.txt](/llms.txt).
> A full single-fetch corpus is available at [llms-full.txt](/llms-full.txt).
---
title: "List traces"
description: "List distributed traces recorded for a workspace, optionally scoped to a single deployment."
method: "GET"
endpoint: "/api/v1/traces"
order: 4
last_verified: 2026-07-27
---

<ApiEndpoint
  method="GET"
  endpoint="/api/v1/traces"
  description="List distributed traces recorded for a workspace, optionally scoped to a single deployment."
>
  <section>
    ### Query parameters

    <ApiAttribute name="workspace_id" type="string" description="The workspace's UUID. Required." required={true} />
    <ApiAttribute name="deployment_id" type="string" description="Restrict to a single deployment." required={false} />
    <ApiAttribute name="service" type="string" description="Filter to a single service name." required={false} />
    <ApiAttribute name="since" type="string" description="Start of the time range, as nanoseconds or RFC 3339. Defaults to 24 hours ago." required={false} />
    <ApiAttribute name="until" type="string" description="End of the time range, as nanoseconds or RFC 3339. Defaults to now." required={false} />
    <ApiAttribute name="min_duration_ms" type="integer" description="Only return traces at least this long." required={false} />
    <ApiAttribute name="limit" type="integer" description="Maximum traces to return. Defaults to 100." required={false} />
  </section>

  <section>
    ### Response

    ```json {{ title: 'Response' }}
    {
      "items": [
        {
          "trace_id": "4f6a2e1b8c9d7f3a5e2b1c4d6a8f9e0b",
          "start_ns": 1753612801123000000,
          "end_ns": 1753612805123000000,
          "duration_ms": 4000,
          "span_count": 12
        }
      ],
      "count": 1,
      "next_offset": 0
    }
    ```
  </section>
</ApiEndpoint>