feat(rest-api): add type-aware attribute filter to GET /v1/spans

app/src/openapi/index.d.ts

@@ -4925,6 +4925,14 @@ export interface operations {
         end_time?: string | null;
         /** @description Filter by one or more trace IDs */
         trace_id?: string[] | null;
+        /** @description Filter by parent span ID. Use "null" to get root spans only. */
+        parent_id?: string | null;
+        /** @description Filter by span name(s) */
+        name?: string[] | null;
+        /** @description Filter by status code(s). Values: OK, ERROR, UNSET */
+        status_code?: string[] | null;
+        /** @description Filter by attribute key:value pairs. Format: key:value (dot-separated keys, e.g. llm.model_name:gpt-4). Multiple filters are ANDed. Values may contain colons (split is on first colon only). Type-aware comparison: bare integers (42), floats (3.14), and booleans (true/false) are compared as their native types; quoted strings ("42") are compared as strings. */
+        attribute?: string[] | null;
       };
       header?: never;
       path: {
@@ -4986,6 +4994,16 @@ export interface operations {
         end_time?: string | null;
         /** @description Filter by one or more trace IDs */
         trace_id?: string[] | null;
+        /** @description Filter by parent span ID. Use "null" to get root spans only. */
+        parent_id?: string | null;
+        /** @description Filter by span name(s) */
+        name?: string[] | null;
+        /** @description Filter by span kind(s). Values: LLM, CHAIN, TOOL, RETRIEVER, EMBEDDING, AGENT, RERANKER, GUARDRAIL, EVALUATOR, UNKNOWN */
+        span_kind?: string[] | null;
+        /** @description Filter by status code(s). Values: OK, ERROR, UNSET */
+        status_code?: string[] | null;
+        /** @description Filter by attribute key:value pairs. Format: key:value (dot-separated keys, e.g. llm.model_name:gpt-4). Multiple filters are ANDed. Values may contain colons (split is on first colon only). Type-aware comparison: bare integers (42), floats (3.14), and booleans (true/false) are compared as their native types; quoted strings ("42") are compared as strings. */
+        attribute?: string[] | null;
       };
       header?: never;
       path: {

js/packages/phoenix-cli/src/commands/span.ts

@@ -30,6 +30,7 @@ interface SpanListOptions {
   name?: string[];
   traceId?: string[];
   parentId?: string;
+  attribute?: string[];
   includeAnnotations?: boolean;
 }
 
@@ -47,6 +48,7 @@ async function fetchSpansForProject(
     names?: string[];
     spanKinds?: string[];
     statusCodes?: string[];
+    attribute?: string[];
     limit: number;
   }
 ): Promise<Span[]> {
@@ -72,6 +74,7 @@ async function fetchSpansForProject(
             name: options.names,
             span_kind: options.spanKinds,
             status_code: options.statusCodes,
+            attribute: options.attribute,
           },
         },
       }
@@ -171,6 +174,7 @@ async function spanListHandler(
         names: options.name,
         spanKinds: options.spanKind,
         statusCodes: options.statusCode,
+        attribute: options.attribute,
       }
     );
 
@@ -292,6 +296,10 @@ export function createSpanListCommand(): Command {
       "--parent-id <id>",
       'Filter by parent span ID (use "null" for root spans only)'
     )
+    .option(
+      "--attribute <filters...>",
+      'Filter by attribute key-value pairs (e.g., "llm.model_name:gpt-4")'
+    )
     .option("--include-annotations", "Include span annotations in the output")
     .action(spanListHandler);
 }

js/packages/phoenix-client/src/constants/serverRequirements.ts

@@ -76,6 +76,14 @@ export const LIST_PROJECT_TRACES: RouteRequirement = {
   minServerVersion: [13, 15, 0],
 };
 
+export const GET_SPANS_ATTRIBUTE_FILTER: ParameterRequirement = {
+  kind: "parameter",
+  parameterName: "attribute",
+  parameterLocation: "query",
+  route: "GET /v1/projects/{id}/spans",
+  minServerVersion: [13, 25, 0],
+};
+
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -90,5 +98,6 @@ export const ALL_REQUIREMENTS: readonly CapabilityRequirement[] = [
   ANNOTATE_SESSIONS,
   GET_SPANS_TRACE_IDS,
   GET_SPANS_FILTERS,
+  GET_SPANS_ATTRIBUTE_FILTER,
   LIST_PROJECT_TRACES,
 ] as const;

js/packages/phoenix-client/src/spans/getSpans.ts

@@ -1,6 +1,7 @@
 import type { operations } from "../__generated__/api/v1";
 import { createClient } from "../client";
 import {
+  GET_SPANS_ATTRIBUTE_FILTER,
   GET_SPANS_FILTERS,
   GET_SPANS_TRACE_IDS,
 } from "../constants/serverRequirements";
@@ -34,6 +35,8 @@ export interface GetSpansParams extends ClientFn {
   spanKind?: SpanKindFilter | SpanKindFilter[] | null;
   /** Filter by status code(s) (OK, ERROR, UNSET) */
   statusCode?: SpanStatusCode | SpanStatusCode[] | null;
+  /** Filter by attribute value(s). Format: "attribute.path:value". Type-aware: bare integers/floats/booleans compared as native types; quoted strings forced to string comparison. */
+  attribute?: string | string[] | null;
 }
 
 export type GetSpansResponse = operations["getSpans"]["responses"]["200"];
@@ -116,6 +119,7 @@ export async function getSpans({
   name,
   spanKind,
   statusCode,
+  attribute,
 }: GetSpansParams): Promise<GetSpansResult> {
   const client = _client ?? createClient();
   if (traceIds) {
@@ -124,6 +128,12 @@ export async function getSpans({
   if (name != null || spanKind != null || statusCode != null) {
     await ensureServerCapability({ client, requirement: GET_SPANS_FILTERS });
   }
+  if (attribute != null) {
+    await ensureServerCapability({
+      client,
+      requirement: GET_SPANS_ATTRIBUTE_FILTER,
+    });
+  }
   const projectIdentifier = resolveProjectIdentifier(project);
 
   const params: NonNullable<operations["getSpans"]["parameters"]["query"]> = {
@@ -163,6 +173,10 @@ export async function getSpans({
     params.status_code = Array.isArray(statusCode) ? statusCode : [statusCode];
   }
 
+  if (attribute) {
+    params.attribute = Array.isArray(attribute) ? attribute : [attribute];
+  }
+
   const { data, error } = await client.GET(
     "/v1/projects/{project_identifier}/spans",
     {

js/packages/phoenix-client/test/spans/getSpans.test.ts

@@ -213,6 +213,73 @@ describe("getSpans", () => {
     });
   });
 
+  describe("attribute parameter", () => {
+    it("should send attribute as array when given a single string", async () => {
+      await getSpans({
+        project: { projectName: "test-project" },
+        attribute: "llm.model_name:gpt-4",
+      });
+
+      expect(mockGet).toHaveBeenCalledWith(
+        "/v1/projects/{project_identifier}/spans",
+        expect.objectContaining({
+          params: expect.objectContaining({
+            query: expect.objectContaining({
+              attribute: ["llm.model_name:gpt-4"],
+            }),
+          }),
+        })
+      );
+    });
+
+    it("should send attribute as array when given an array", async () => {
+      await getSpans({
+        project: { projectName: "test-project" },
+        attribute: ["llm.model_name:gpt-4", "llm.provider:openai"],
+      });
+
+      expect(mockGet).toHaveBeenCalledWith(
+        "/v1/projects/{project_identifier}/spans",
+        expect.objectContaining({
+          params: expect.objectContaining({
+            query: expect.objectContaining({
+              attribute: ["llm.model_name:gpt-4", "llm.provider:openai"],
+            }),
+          }),
+        })
+      );
+    });
+
+    it("should not send attribute when undefined", async () => {
+      await getSpans({
+        project: { projectName: "test-project" },
+      });
+
+      const callArgs = mockGet.mock.calls[0]?.[1];
+      expect(callArgs.params.query).not.toHaveProperty("attribute");
+    });
+
+    it("should send attribute combined with other filters", async () => {
+      await getSpans({
+        project: { projectName: "test-project" },
+        spanKind: "LLM",
+        attribute: "llm.model_name:gpt-4",
+      });
+
+      expect(mockGet).toHaveBeenCalledWith(
+        "/v1/projects/{project_identifier}/spans",
+        expect.objectContaining({
+          params: expect.objectContaining({
+            query: expect.objectContaining({
+              span_kind: ["LLM"],
+              attribute: ["llm.model_name:gpt-4"],
+            }),
+          }),
+        })
+      );
+    });
+  });
+
   describe("parentId parameter", () => {
     it('should send parent_id="null" to get root spans only', async () => {
       await getSpans({

packages/phoenix-client/src/phoenix/client/constants/server_requirements.py

@@ -50,6 +50,13 @@
     min_server_version=Version(13, 15, 0),
 )
 
+GET_SPANS_ATTRIBUTE_V2 = ParameterRequirement(
+    parameter_name="attribute",
+    parameter_location="query",
+    route="GET /v1/projects/{id}/spans",
+    min_server_version=Version(13, 25, 0),
+)
+
 LIST_PROJECT_TRACES = RouteRequirement(
     method="GET",
     path="/v1/projects/{project_identifier}/traces",

packages/phoenix-client/src/phoenix/client/resources/spans/__init__.py

@@ -27,14 +27,46 @@
     import pandas as pd
 
 from phoenix.client.__generated__ import v1
-from phoenix.client.constants.server_requirements import GET_SPANS_FILTERS, GET_SPANS_TRACE_IDS
+from phoenix.client.constants.server_requirements import (
+    GET_SPANS_ATTRIBUTE_V2,
+    GET_SPANS_FILTERS,
+    GET_SPANS_TRACE_IDS,
+)
 from phoenix.client.exceptions import DuplicateSpanInfo, InvalidSpanInfo, SpanCreationError
 from phoenix.client.helpers.spans import dataframe_to_spans as _dataframe_to_spans
 from phoenix.client.types.spans import SpanQuery
 from phoenix.client.utils.id_handling import is_node_id
 
 logger = logging.getLogger(__name__)
 
+
+def _serialize_attribute_value(v: Union[str, int, float, bool]) -> str:
+    """Serialize a typed attribute value for the ``attribute=key:value`` query param.
+
+    - int/float: str(v). Non-finite floats raise ValueError.
+    - bool: json.dumps(v) → "true"/"false".
+    - str: passed as-is, unless json.loads(v) would parse it as a non-string type,
+      in which case it is JSON-quoted to force string comparison on the server.
+    """
+    if isinstance(v, bool):
+        return json.dumps(v)
+    if isinstance(v, int):
+        return str(v)
+    if isinstance(v, float):
+        import math
+
+        if not math.isfinite(v):
+            raise ValueError(f"Non-finite float values are not supported: {v!r}")
+        return str(v)
+    try:
+        parsed = json.loads(v)
+    except (json.JSONDecodeError, ValueError):
+        return v
+    if not isinstance(parsed, str):
+        return json.dumps(v)
+    return v
+
+
 # Re-export generated types
 AnnotateSpanDocumentsRequestBody = v1.AnnotateSpanDocumentsRequestBody
 AnnotateSpanDocumentsResponseBody = v1.AnnotateSpanDocumentsResponseBody
@@ -442,6 +474,7 @@ def get_spans(
         name: Optional[Union[str, Sequence[str]]] = None,
         span_kind: Optional[Union[str, Sequence[str]]] = None,
         status_code: Optional[Union[str, Sequence[str]]] = None,
+        attribute: Optional[dict[str, Union[str, int, float, bool]]] = None,
         limit: int = 100,
         timeout: Optional[int] = DEFAULT_TIMEOUT_IN_SECONDS,
     ) -> list[v1.Span]:
@@ -464,6 +497,12 @@ def get_spans(
                 by (e.g. LLM, CHAIN, TOOL). Requires Phoenix server >= 13.15.0.
             status_code (Optional[Union[str, Sequence[str]]]): Optional status code(s) to
                 filter by (e.g. OK, ERROR, UNSET). Requires Phoenix server >= 13.15.0.
+            attribute (Optional[dict[str, Union[str, int, float, bool]]]): Optional dictionary
+                of attribute key-value pairs to filter by (AND semantics). Serialized as
+                repeated ``attribute=key:value`` query params. Type-aware: int/float use
+                str(v), bool uses json.dumps(v), str values that parse as non-string JSON
+                are quoted to force string comparison.
+                Requires Phoenix server >= 13.25.0.
             limit (int): Maximum number of spans to return. Defaults to 100.
             timeout (Optional[int]): Optional request timeout in seconds.
 
@@ -472,11 +511,15 @@ def get_spans(
 
         Raises:
             httpx.HTTPStatusError: If the API returns an error response.
+            TypeError: If a value in ``attribute`` is not str, int, float, or bool.
+            ValueError: If a float value in ``attribute`` is non-finite (nan or inf).
         """
         if trace_ids:
             self._guard.require(GET_SPANS_TRACE_IDS)
         if name or span_kind or status_code:
             self._guard.require(GET_SPANS_FILTERS)
+        if attribute:
+            self._guard.require(GET_SPANS_ATTRIBUTE_V2)
         all_spans: list[v1.Span] = []
         cursor: Optional[str] = None
         page_size = min(100, limit)
@@ -505,6 +548,10 @@ def get_spans(
                 params["status_code"] = (
                     [status_code] if isinstance(status_code, str) else list(status_code)
                 )
+            if attribute:
+                params["attribute"] = [
+                    f"{k}:{_serialize_attribute_value(v)}" for k, v in attribute.items()
+                ]
             if cursor:
                 params["cursor"] = cursor
 
@@ -1704,6 +1751,7 @@ async def get_spans(
         name: Optional[Union[str, Sequence[str]]] = None,
         span_kind: Optional[Union[str, Sequence[str]]] = None,
         status_code: Optional[Union[str, Sequence[str]]] = None,
+        attribute: Optional[dict[str, Union[str, int, float, bool]]] = None,
         limit: int = 100,
         timeout: Optional[int] = DEFAULT_TIMEOUT_IN_SECONDS,
     ) -> list[v1.Span]:
@@ -1726,6 +1774,12 @@ async def get_spans(
                 by (e.g. LLM, CHAIN, TOOL). Requires Phoenix server >= 13.15.0.
             status_code (Optional[Union[str, Sequence[str]]]): Optional status code(s) to
                 filter by (e.g. OK, ERROR, UNSET). Requires Phoenix server >= 13.15.0.
+            attribute (Optional[dict[str, Union[str, int, float, bool]]]): Optional dictionary
+                of attribute key-value pairs to filter by (AND semantics). Serialized as
+                repeated ``attribute=key:value`` query params. Type-aware: int/float use
+                str(v), bool uses json.dumps(v), str values that parse as non-string JSON
+                are quoted to force string comparison.
+                Requires Phoenix server >= 13.25.0.
             limit (int): Maximum number of spans to return. Defaults to 100.
             timeout (Optional[int]): Optional request timeout in seconds.
 
@@ -1734,11 +1788,15 @@ async def get_spans(
 
         Raises:
             httpx.HTTPStatusError: If the API returns an error response.
+            TypeError: If a value in ``attribute`` is not str, int, float, or bool.
+            ValueError: If a float value in ``attribute`` is non-finite (nan or inf).
         """
         if trace_ids:
             await self._guard.require(GET_SPANS_TRACE_IDS)
         if name or span_kind or status_code:
             await self._guard.require(GET_SPANS_FILTERS)
+        if attribute:
+            await self._guard.require(GET_SPANS_ATTRIBUTE_V2)
         all_spans: list[v1.Span] = []
         cursor: Optional[str] = None
         page_size = min(100, limit)
@@ -1767,6 +1825,10 @@ async def get_spans(
                 params["status_code"] = (
                     [status_code] if isinstance(status_code, str) else list(status_code)
                 )
+            if attribute:
+                params["attribute"] = [
+                    f"{k}:{_serialize_attribute_value(v)}" for k, v in attribute.items()
+                ]
             if cursor:
                 params["cursor"] = cursor