feat: switch span list to EAP spans endpoint and show span IDs in trace view

Use the server-side spans search endpoint (dataset=spans) for `span list`
instead of fetching the full trace tree and filtering client-side. Add
`translateSpanQuery` to rewrite CLI shorthand keys (op→span.op,
duration→span.duration) for the API.

Also fix trace view showing `undefined` for span IDs — the trace detail
API returns `event_id` instead of `span_id`, so normalize in
`getDetailedTrace`. Append span IDs (dimmed) to each tree line.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: betegon

src/commands/span/list.ts

@@ -5,7 +5,7 @@
  */
 
 import type { SentryContext } from "../../context.js";
-import { getDetailedTrace } from "../../lib/api-client.js";
+import { listSpans } from "../../lib/api-client.js";
 import {
   parseOrgProjectArg,
   parseSlashSeparatedArg,
@@ -14,9 +14,8 @@ import {
 import { buildCommand } from "../../lib/command.js";
 import { ContextError, ValidationError } from "../../lib/errors.js";
 import {
-  applySpanFilter,
-  flattenSpanTree,
-  parseSpanQuery,
+  spanListItemToFlatSpan,
+  translateSpanQuery,
   writeFooter,
   writeJsonList,
   writeSpanTable,
@@ -230,42 +229,31 @@ export const listCommand = buildCommand({
 
     setContext([target.org], [target.project]);
 
-    // Fetch trace data
-    const timestamp = Math.floor(Date.now() / 1000);
-    const spans = await getDetailedTrace(target.org, traceId, timestamp);
-
-    if (spans.length === 0) {
-      throw new ValidationError(
-        `No trace found with ID "${traceId}".\n\n` +
-          "Make sure the trace ID is correct and the trace was sent recently."
-      );
-    }
-
-    // Flatten and filter
-    let flatSpans = flattenSpanTree(spans);
-    const totalSpans = flatSpans.length;
-
+    // Build server-side query
+    const queryParts = [`trace:${traceId}`];
     if (flags.query) {
-      const filter = parseSpanQuery(flags.query);
-      flatSpans = applySpanFilter(flatSpans, filter);
+      queryParts.push(translateSpanQuery(flags.query));
     }
-    const matchedSpans = flatSpans.length;
-
-    // Sort
-    if (flags.sort === "duration") {
-      flatSpans.sort((a, b) => (b.duration_ms ?? -1) - (a.duration_ms ?? -1));
-    }
-    // "time" is already in depth-first (start_timestamp) order from flattenSpanTree
+    const apiQuery = queryParts.join(" ");
+
+    // Fetch spans from EAP endpoint
+    const { data: spanItems, nextCursor } = await listSpans(
+      target.org,
+      target.project,
+      {
+        query: apiQuery,
+        sort: flags.sort,
+        limit: flags.limit,
+      }
+    );
 
-    // Apply limit
-    const hasMore = flatSpans.length > flags.limit;
-    flatSpans = flatSpans.slice(0, flags.limit);
+    const flatSpans = spanItems.map(spanListItemToFlatSpan);
+    const hasMore = nextCursor !== undefined;
 
     if (flags.json) {
       writeJsonList(stdout, flatSpans, {
         hasMore,
         fields: flags.fields,
-        extra: { totalSpans, matchedSpans },
       });
       return;
     }
@@ -279,11 +267,7 @@ export const listCommand = buildCommand({
     writeSpanTable(stdout, flatSpans);
 
     // Footer
-    const filterNote =
-      matchedSpans < totalSpans
-        ? ` (${matchedSpans} matched, ${totalSpans} total)`
-        : ` (${totalSpans} total)`;
-    const countText = `Showing ${flatSpans.length} span${flatSpans.length === 1 ? "" : "s"}${filterNote}.`;
+    const countText = `Showing ${flatSpans.length} span${flatSpans.length === 1 ? "" : "s"}.`;
 
     if (hasMore) {
       writeFooter(stdout, `${countText} Use --limit to see more.`);

src/lib/api-client.ts

@@ -50,6 +50,9 @@ import {
   type SentryTeam,
   type SentryUser,
   SentryUserSchema,
+  type SpanListItem,
+  type SpansResponse,
+  SpansResponseSchema,
   type TraceLog,
   TraceLogsResponseSchema,
   type TraceSpan,
@@ -1503,7 +1506,24 @@ export async function getDetailedTrace(
       },
     }
   );
-  return data;
+  return data.map(normalizeTraceSpan);
+}
+
+/**
+ * The trace detail API (`/trace/{id}/`) returns each span's unique identifier
+ * as `event_id` rather than `span_id`. The value is the same 16-hex-char span
+ * ID that `parent_span_id` references on child spans. We copy it to `span_id`
+ * so the rest of the codebase can use a single, predictable field name.
+ */
+function normalizeTraceSpan(span: TraceSpan): TraceSpan {
+  const normalized = { ...span };
+  if (!normalized.span_id && normalized.event_id) {
+    normalized.span_id = normalized.event_id;
+  }
+  if (normalized.children) {
+    normalized.children = normalized.children.map(normalizeTraceSpan);
+  }
+  return normalized;
 }
 
 /** Fields to request from the transactions API */
@@ -1583,6 +1603,74 @@ export async function listTransactions(
   return { data: response.data, nextCursor };
 }
 
+/** Fields to request from the spans API */
+const SPAN_FIELDS = [
+  "id",
+  "parent_span",
+  "span.op",
+  "description",
+  "span.duration",
+  "timestamp",
+  "project",
+  "transaction",
+  "trace",
+];
+
+type ListSpansOptions = {
+  /** Search query using Sentry query syntax */
+  query?: string;
+  /** Maximum number of spans to return */
+  limit?: number;
+  /** Sort order: "time" (newest first) or "duration" (slowest first) */
+  sort?: "time" | "duration";
+  /** Time period for spans (e.g., "7d", "24h") */
+  statsPeriod?: string;
+  /** Pagination cursor to resume from a previous page */
+  cursor?: string;
+};
+
+/**
+ * List spans using the EAP spans search endpoint.
+ * Uses the Explore/Events API with dataset=spans.
+ *
+ * @param orgSlug - Organization slug
+ * @param projectSlug - Project slug or numeric ID
+ * @param options - Query options (query, limit, sort, statsPeriod, cursor)
+ * @returns Paginated response with span items and optional next cursor
+ */
+export async function listSpans(
+  orgSlug: string,
+  projectSlug: string,
+  options: ListSpansOptions = {}
+): Promise<PaginatedResponse<SpanListItem[]>> {
+  const isNumericProject = isAllDigits(projectSlug);
+  const projectFilter = isNumericProject ? "" : `project:${projectSlug}`;
+  const fullQuery = [projectFilter, options.query].filter(Boolean).join(" ");
+
+  const regionUrl = await resolveOrgRegion(orgSlug);
+
+  const { data: response, headers } = await apiRequestToRegion<SpansResponse>(
+    regionUrl,
+    `/organizations/${orgSlug}/events/`,
+    {
+      params: {
+        dataset: "spans",
+        field: SPAN_FIELDS,
+        project: isNumericProject ? projectSlug : undefined,
+        query: fullQuery || undefined,
+        per_page: options.limit || 10,
+        statsPeriod: options.statsPeriod ?? "7d",
+        sort: options.sort === "duration" ? "-span.duration" : "-timestamp",
+        cursor: options.cursor,
+      },
+      schema: SpansResponseSchema,
+    }
+  );
+
+  const { nextCursor } = parseLinkHeader(headers.get("link") ?? null);
+  return { data: response.data, nextCursor };
+}
+
 // Issue update functions
 
 /**

src/lib/formatters/human.ts

@@ -1067,6 +1067,8 @@ function formatSpanSimple(span: TraceSpan, opts: FormatSpanOptions): void {
     line += `  ${muted(`(${prettyMs(durationMs)})`)}`;
   }
 
+  line += `  ${muted(span.span_id)}`;
+
   lines.push(line);
 
   if (currentDepth < maxDepth) {