@arizeai/phoenix-client 6.5.1 → 6.5.2

package/README.md

@@ -298,6 +298,200 @@ const experiment = await runExperiment({
 
 > **Hint:** Tasks and evaluators are instrumented using [OpenTelemetry](https://opentelemetry.io/). You can view detailed traces of experiment runs and evaluations directly in the Phoenix UI for debugging and performance analysis.
 
+## Traces
+
+The `@arizeai/phoenix-client` package provides a `traces` export for retrieving trace data from Phoenix projects.
+
+### Fetching Traces
+
+Use `getTraces` to retrieve traces with optional filtering, sorting, and pagination.
+
+```ts
+import { getTraces } from "@arizeai/phoenix-client/traces";
+
+// Get the latest 10 traces
+const result = await getTraces({
+  project: { projectName: "my-project" },
+  limit: 10,
+});
+console.log(result.data); // array of trace objects
+
+// Filter by time range and include full span details
+const detailed = await getTraces({
+  project: { projectName: "my-project" },
+  startTime: "2026-03-01T00:00:00Z",
+  endTime: new Date(),
+  includeSpans: true,
+  sort: "latency_ms",
+  order: "desc",
+});
+
+// Filter by session
+const sessionTraces = await getTraces({
+  project: { projectName: "my-project" },
+  sessionId: "my-session-id",
+});
+```
+
+| Parameter      | Type                           | Description                                |
+| -------------- | ------------------------------ | ------------------------------------------ |
+| `project`      | `ProjectIdentifier`            | The project (by name or ID) — **required** |
+| `startTime`    | `Date \| string \| null`       | Inclusive lower bound on trace start time  |
+| `endTime`      | `Date \| string \| null`       | Exclusive upper bound on trace start time  |
+| `sort`         | `"start_time" \| "latency_ms"` | Sort field                                 |
+| `order`        | `"asc" \| "desc"`              | Sort direction                             |
+| `limit`        | `number`                       | Maximum number of traces to return         |
+| `cursor`       | `string \| null`               | Pagination cursor (Trace GlobalID)         |
+| `includeSpans` | `boolean`                      | Include full span details for each trace   |
+| `sessionId`    | `string \| string[] \| null`   | Filter traces by session identifier(s)     |
+
+### Pagination
+
+Use the `cursor` from a previous result to fetch the next page:
+
+```ts
+import { getTraces } from "@arizeai/phoenix-client/traces";
+
+let cursor: string | null = null;
+const allTraces = [];
+
+do {
+  const result = await getTraces({
+    project: { projectName: "my-project" },
+    limit: 50,
+    cursor,
+  });
+  allTraces.push(...result.data);
+  cursor = result.nextCursor ?? null;
+} while (cursor);
+```
+
+> **Note:** Requires Phoenix server >= 13.15.0.
+
+## Spans
+
+The `@arizeai/phoenix-client` package provides a `spans` export for querying spans with powerful filtering.
+
+### Fetching Spans
+
+Use `getSpans` to retrieve spans with filtering by kind, status, name, trace, and more.
+
+```ts
+import { getSpans } from "@arizeai/phoenix-client/spans";
+
+// Get recent spans
+const result = await getSpans({
+  project: { projectName: "my-project" },
+  limit: 100,
+});
+
+// Filter by span kind and status
+const errorLLMSpans = await getSpans({
+  project: { projectName: "my-project" },
+  spanKind: "LLM",
+  statusCode: "ERROR",
+});
+
+// Filter by name and trace
+const spans = await getSpans({
+  project: { projectName: "my-project" },
+  name: "chat_completion",
+  traceIds: ["trace-abc", "trace-def"],
+});
+
+// Root spans only
+const rootSpans = await getSpans({
+  project: { projectName: "my-project" },
+  parentId: null,
+});
+```
+
+| Parameter    | Type                                 | Description                                                     |
+| ------------ | ------------------------------------ | --------------------------------------------------------------- |
+| `project`    | `ProjectIdentifier`                  | The project (by name or ID) — **required**                      |
+| `startTime`  | `Date \| string \| null`             | Inclusive lower bound time                                      |
+| `endTime`    | `Date \| string \| null`             | Exclusive upper bound time                                      |
+| `limit`      | `number`                             | Maximum number of spans to return                               |
+| `cursor`     | `string \| null`                     | Pagination cursor (Span GlobalID)                               |
+| `traceIds`   | `string[] \| null`                   | Filter by trace ID(s)                                           |
+| `parentId`   | `string \| null`                     | Filter by parent span ID (`null` for root spans only)           |
+| `name`       | `string \| string[] \| null`         | Filter by span name(s)                                          |
+| `spanKind`   | `SpanKindFilter \| SpanKindFilter[]` | Filter by span kind (`LLM`, `CHAIN`, `TOOL`, `RETRIEVER`, etc.) |
+| `statusCode` | `SpanStatusCode \| SpanStatusCode[]` | Filter by status code (`OK`, `ERROR`, `UNSET`)                  |
+
+## Span Annotations
+
+The `spans` export also provides functions for managing span annotations — adding evaluations, feedback, and labels to spans.
+
+### Adding a Single Annotation
+
+```ts
+import { addSpanAnnotation } from "@arizeai/phoenix-client/spans";
+
+const result = await addSpanAnnotation({
+  spanAnnotation: {
+    spanId: "f8b1c3a2d4e5f678",
+    name: "correctness",
+    label: "correct",
+    score: 1.0,
+    explanation: "The response accurately answered the question",
+    annotatorKind: "HUMAN",
+  },
+  sync: true, // wait for the annotation ID to be returned
+});
+// result: { id: "annotation-id" } when sync: true, null when sync: false
+```
+
+### Logging Multiple Annotations
+
+```ts
+import { logSpanAnnotations } from "@arizeai/phoenix-client/spans";
+
+const results = await logSpanAnnotations({
+  spanAnnotations: [
+    {
+      spanId: "f8b1c3a2d4e5f678",
+      name: "relevance",
+      label: "relevant",
+      score: 0.95,
+      annotatorKind: "LLM",
+    },
+    {
+      spanId: "a1b2c3d4e5f67890",
+      name: "relevance",
+      label: "irrelevant",
+      score: 0.2,
+      annotatorKind: "LLM",
+    },
+  ],
+  sync: true,
+});
+// results: [{ id: "..." }, { id: "..." }]
+```
+
+### Fetching Span Annotations
+
+```ts
+import { getSpanAnnotations } from "@arizeai/phoenix-client/spans";
+
+const result = await getSpanAnnotations({
+  project: { projectName: "my-project" },
+  spanIds: ["f8b1c3a2d4e5f678", "a1b2c3d4e5f67890"],
+  includeAnnotationNames: ["relevance", "correctness"],
+  limit: 100,
+});
+console.log(result.data); // array of span annotation objects
+```
+
+| Parameter                | Type                | Description                                      |
+| ------------------------ | ------------------- | ------------------------------------------------ |
+| `project`                | `ProjectIdentifier` | The project (by name or ID) — **required**       |
+| `spanIds`                | `string[]`          | Span IDs to fetch annotations for — **required** |
+| `includeAnnotationNames` | `string[]`          | Only return annotations with these names         |
+| `excludeAnnotationNames` | `string[]`          | Exclude annotations with these names             |
+| `cursor`                 | `string \| null`    | Pagination cursor                                |
+| `limit`                  | `number`            | Maximum annotations to return                    |
+
 ## Examples
 
 To run examples, install dependencies using `pnpm` and run:

package/dist/esm/constants/serverRequirements.d.ts

@@ -19,6 +19,7 @@ export declare const LIST_PROJECT_SESSIONS: RouteRequirement;
 export declare const ANNOTATE_SESSIONS: RouteRequirement;
 export declare const GET_SPANS_TRACE_IDS: ParameterRequirement;
 export declare const GET_SPANS_FILTERS: ParameterRequirement;
+export declare const LIST_PROJECT_TRACES: RouteRequirement;
 /**
  * Aggregate list of every known capability requirement.
  *

package/dist/esm/constants/serverRequirements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"serverRequirements.d.ts","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,gBAK5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,gBAK7B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,gBAKnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBAK/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,oBAMjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,oBAM/B,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,qBAAqB,EAQnD,CAAC"}
+{"version":3,"file":"serverRequirements.d.ts","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EACV,qBAAqB,EACrB,oBAAoB,EACpB,gBAAgB,EACjB,MAAM,6BAA6B,CAAC;AAErC,eAAO,MAAM,WAAW,EAAE,gBAKzB,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,gBAK5B,CAAC;AAEF,eAAO,MAAM,eAAe,EAAE,gBAK7B,CAAC;AAEF,eAAO,MAAM,qBAAqB,EAAE,gBAKnC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,gBAK/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,oBAMjC,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,oBAM/B,CAAC;AAEF,eAAO,MAAM,mBAAmB,EAAE,gBAKjC,CAAC;AAEF;;;;;GAKG;AACH,eAAO,MAAM,gBAAgB,EAAE,SAAS,qBAAqB,EASnD,CAAC"}

package/dist/esm/constants/serverRequirements.js

@@ -55,6 +55,12 @@ export const GET_SPANS_FILTERS = {
     route: "GET /v1/projects/{id}/spans",
     minServerVersion: [13, 15, 0],
 };
+export const LIST_PROJECT_TRACES = {
+    kind: "route",
+    method: "GET",
+    path: "/v1/projects/{project_identifier}/traces",
+    minServerVersion: [13, 15, 0],
+};
 /**
  * Aggregate list of every known capability requirement.
  *
@@ -69,5 +75,6 @@ export const ALL_REQUIREMENTS = [
     ANNOTATE_SESSIONS,
     GET_SPANS_TRACE_IDS,
     GET_SPANS_FILTERS,
+    LIST_PROJECT_TRACES,
 ];
 //# sourceMappingURL=serverRequirements.js.map

package/dist/esm/constants/serverRequirements.js.map

@@ -1 +1 @@
-{"version":3,"file":"serverRequirements.js","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,2BAA2B;IACjC,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,2BAA2B;IACjC,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAqB;IAC/C,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,qBAAqB;IAC3B,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACrD,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,oCAAoC;IAC1C,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAqB;IACjD,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,yBAAyB;IAC/B,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAyB;IACvD,IAAI,EAAE,WAAW;IACjB,aAAa,EAAE,UAAU;IACzB,iBAAiB,EAAE,OAAO;IAC1B,KAAK,EAAE,6BAA6B;IACpC,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAyB;IACrD,IAAI,EAAE,WAAW;IACjB,aAAa,EAAE,WAAW;IAC1B,iBAAiB,EAAE,OAAO;IAC1B,KAAK,EAAE,6BAA6B;IACpC,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqC;IAChE,WAAW;IACX,cAAc;IACd,eAAe;IACf,qBAAqB;IACrB,iBAAiB;IACjB,mBAAmB;IACnB,iBAAiB;CACT,CAAC"}
+{"version":3,"file":"serverRequirements.js","sourceRoot":"","sources":["../../../src/constants/serverRequirements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAQH,MAAM,CAAC,MAAM,WAAW,GAAqB;IAC3C,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,2BAA2B;IACjC,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,cAAc,GAAqB;IAC9C,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,QAAQ;IAChB,IAAI,EAAE,2BAA2B;IACjC,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,eAAe,GAAqB;IAC/C,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,qBAAqB;IAC3B,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,qBAAqB,GAAqB;IACrD,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,oCAAoC;IAC1C,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAqB;IACjD,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,yBAAyB;IAC/B,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAyB;IACvD,IAAI,EAAE,WAAW;IACjB,aAAa,EAAE,UAAU;IACzB,iBAAiB,EAAE,OAAO;IAC1B,KAAK,EAAE,6BAA6B;IACpC,gBAAgB,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,CAAC,MAAM,iBAAiB,GAAyB;IACrD,IAAI,EAAE,WAAW;IACjB,aAAa,EAAE,WAAW;IAC1B,iBAAiB,EAAE,OAAO;IAC1B,KAAK,EAAE,6BAA6B;IACpC,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF,MAAM,CAAC,MAAM,mBAAmB,GAAqB;IACnD,IAAI,EAAE,OAAO;IACb,MAAM,EAAE,KAAK;IACb,IAAI,EAAE,0CAA0C;IAChD,gBAAgB,EAAE,CAAC,EAAE,EAAE,EAAE,EAAE,CAAC,CAAC;CAC9B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAqC;IAChE,WAAW;IACX,cAAc;IACd,eAAe;IACf,qBAAqB;IACrB,iBAAiB;IACjB,mBAAmB;IACnB,iBAAiB;IACjB,mBAAmB;CACX,CAAC"}

package/dist/esm/traces/getTraces.d.ts

@@ -0,0 +1,78 @@
+import type { operations } from "../__generated__/api/v1.js";
+import type { ClientFn } from "../types/core.js";
+import type { ProjectIdentifier } from "../types/projects.js";
+/**
+ * Parameters for getting traces from a project.
+ */
+export interface GetTracesParams extends ClientFn {
+    /** The project to get traces from */
+    project: ProjectIdentifier;
+    /** Inclusive lower bound time. Must be a valid ISO 8601 string or Date object. */
+    startTime?: Date | string | null;
+    /** Exclusive upper bound time. Must be a valid ISO 8601 string or Date object. */
+    endTime?: Date | string | null;
+    /** Sort field */
+    sort?: "start_time" | "latency_ms";
+    /** Sort direction */
+    order?: "asc" | "desc";
+    /** Maximum number of traces to return */
+    limit?: number;
+    /** Pagination cursor (Trace GlobalID) */
+    cursor?: string | null;
+    /** If true, include full span details for each trace */
+    includeSpans?: boolean;
+    /** Filter traces by session identifier(s) (session_id strings or GlobalIDs) */
+    sessionId?: string | string[] | null;
+}
+export type GetTracesResponse = operations["listProjectTraces"]["responses"]["200"];
+export type GetTracesResult = {
+    traces: GetTracesResponse["content"]["application/json"]["data"];
+    nextCursor: GetTracesResponse["content"]["application/json"]["next_cursor"];
+};
+/**
+ * Get traces from a project with filtering and sorting options.
+ *
+ * This method fetches traces from a project with support for time range filtering,
+ * sorting, session filtering, and cursor-based pagination.
+ *
+ * @requires Phoenix server >= 13.15.0
+ *
+ * @param params - The parameters to get traces
+ * @returns A paginated response containing traces and optional next cursor
+ *
+ * @example
+ * ```ts
+ * // Get recent traces from a project
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   limit: 50,
+ * });
+ *
+ * // Get traces in a time range with spans included
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   startTime: new Date("2024-01-01"),
+ *   endTime: new Date("2024-01-02"),
+ *   includeSpans: true,
+ * });
+ *
+ * // Paginate through results
+ * let cursor: string | undefined;
+ * do {
+ *   const result = await getTraces({
+ *     client,
+ *     project: { projectName: "my-project" },
+ *     cursor,
+ *     limit: 100,
+ *   });
+ *   result.traces.forEach(trace => {
+ *     console.log(`Trace: ${trace.trace_id}`);
+ *   });
+ *   cursor = result.nextCursor || undefined;
+ * } while (cursor);
+ * ```
+ */
+export declare function getTraces({ client: _client, project, cursor, limit, startTime, endTime, sort, order, includeSpans, sessionId, }: GetTracesParams): Promise<GetTracesResult>;
+//# sourceMappingURL=getTraces.d.ts.map

package/dist/esm/traces/getTraces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"getTraces.d.ts","sourceRoot":"","sources":["../../../src/traces/getTraces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAG1D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAI3D;;GAEG;AACH,MAAM,WAAW,eAAgB,SAAQ,QAAQ;IAC/C,qCAAqC;IACrC,OAAO,EAAE,iBAAiB,CAAC;IAC3B,kFAAkF;IAClF,SAAS,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IACjC,kFAAkF;IAClF,OAAO,CAAC,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAAC;IAC/B,iBAAiB;IACjB,IAAI,CAAC,EAAE,YAAY,GAAG,YAAY,CAAC;IACnC,qBAAqB;IACrB,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACvB,yCAAyC;IACzC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,wDAAwD;IACxD,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI,CAAC;CACtC;AAED,MAAM,MAAM,iBAAiB,GAC3B,UAAU,CAAC,mBAAmB,CAAC,CAAC,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC;AAEtD,MAAM,MAAM,eAAe,GAAG;IAC5B,MAAM,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;IACjE,UAAU,EAAE,iBAAiB,CAAC,SAAS,CAAC,CAAC,kBAAkB,CAAC,CAAC,aAAa,CAAC,CAAC;CAC7E,CAAC;AAEF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAsB,SAAS,CAAC,EAC9B,MAAM,EAAE,OAAO,EACf,OAAO,EACP,MAAM,EACN,KAAW,EACX,SAAS,EACT,OAAO,EACP,IAAI,EACJ,KAAK,EACL,YAAY,EACZ,SAAS,GACV,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CA2D5C"}

package/dist/esm/traces/getTraces.js

@@ -0,0 +1,96 @@
+import { createClient } from "../client.js";
+import { LIST_PROJECT_TRACES } from "../constants/serverRequirements.js";
+import { resolveProjectIdentifier } from "../types/projects.js";
+import { ensureServerCapability } from "../utils/serverVersionUtils.js";
+/**
+ * Get traces from a project with filtering and sorting options.
+ *
+ * This method fetches traces from a project with support for time range filtering,
+ * sorting, session filtering, and cursor-based pagination.
+ *
+ * @requires Phoenix server >= 13.15.0
+ *
+ * @param params - The parameters to get traces
+ * @returns A paginated response containing traces and optional next cursor
+ *
+ * @example
+ * ```ts
+ * // Get recent traces from a project
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   limit: 50,
+ * });
+ *
+ * // Get traces in a time range with spans included
+ * const result = await getTraces({
+ *   client,
+ *   project: { projectName: "my-project" },
+ *   startTime: new Date("2024-01-01"),
+ *   endTime: new Date("2024-01-02"),
+ *   includeSpans: true,
+ * });
+ *
+ * // Paginate through results
+ * let cursor: string | undefined;
+ * do {
+ *   const result = await getTraces({
+ *     client,
+ *     project: { projectName: "my-project" },
+ *     cursor,
+ *     limit: 100,
+ *   });
+ *   result.traces.forEach(trace => {
+ *     console.log(`Trace: ${trace.trace_id}`);
+ *   });
+ *   cursor = result.nextCursor || undefined;
+ * } while (cursor);
+ * ```
+ */
+export async function getTraces({ client: _client, project, cursor, limit = 100, startTime, endTime, sort, order, includeSpans, sessionId, }) {
+    const client = _client ?? createClient();
+    await ensureServerCapability({ client, requirement: LIST_PROJECT_TRACES });
+    const projectIdentifier = resolveProjectIdentifier(project);
+    const params = {
+        limit,
+    };
+    if (cursor) {
+        params.cursor = cursor;
+    }
+    if (startTime) {
+        params.start_time =
+            startTime instanceof Date ? startTime.toISOString() : startTime;
+    }
+    if (endTime) {
+        params.end_time = endTime instanceof Date ? endTime.toISOString() : endTime;
+    }
+    if (sort) {
+        params.sort = sort;
+    }
+    if (order) {
+        params.order = order;
+    }
+    if (includeSpans) {
+        params.include_spans = true;
+    }
+    if (sessionId) {
+        params.session_identifier = Array.isArray(sessionId)
+            ? sessionId
+            : [sessionId];
+    }
+    const { data, error } = await client.GET("/v1/projects/{project_identifier}/traces", {
+        params: {
+            path: {
+                project_identifier: projectIdentifier,
+            },
+            query: params,
+        },
+    });
+    if (error)
+        throw error;
+    return {
+        traces: data?.data ?? [],
+        nextCursor: data?.next_cursor ?? null,
+    };
+}
+//# sourceMappingURL=getTraces.js.map

package/dist/esm/traces/getTraces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"getTraces.js","sourceRoot":"","sources":["../../../src/traces/getTraces.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,OAAO,EAAE,mBAAmB,EAAE,MAAM,iCAAiC,CAAC;AAGtE,OAAO,EAAE,wBAAwB,EAAE,MAAM,mBAAmB,CAAC;AAC7D,OAAO,EAAE,sBAAsB,EAAE,MAAM,6BAA6B,CAAC;AAkCrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAAC,EAC9B,MAAM,EAAE,OAAO,EACf,OAAO,EACP,MAAM,EACN,KAAK,GAAG,GAAG,EACX,SAAS,EACT,OAAO,EACP,IAAI,EACJ,KAAK,EACL,YAAY,EACZ,SAAS,GACO;IAChB,MAAM,MAAM,GAAG,OAAO,IAAI,YAAY,EAAE,CAAC;IACzC,MAAM,sBAAsB,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,CAAC,CAAC;IAC3E,MAAM,iBAAiB,GAAG,wBAAwB,CAAC,OAAO,CAAC,CAAC;IAE5D,MAAM,MAAM,GAER;QACF,KAAK;KACN,CAAC;IAEF,IAAI,MAAM,EAAE,CAAC;QACX,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC;IACzB,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,CAAC,UAAU;YACf,SAAS,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC;IACpE,CAAC;IAED,IAAI,OAAO,EAAE,CAAC;QACZ,MAAM,CAAC,QAAQ,GAAG,OAAO,YAAY,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC;IAC9E,CAAC;IAED,IAAI,IAAI,EAAE,CAAC;QACT,MAAM,CAAC,IAAI,GAAG,IAAI,CAAC;IACrB,CAAC;IAED,IAAI,KAAK,EAAE,CAAC;QACV,MAAM,CAAC,KAAK,GAAG,KAAK,CAAC;IACvB,CAAC;IAED,IAAI,YAAY,EAAE,CAAC;QACjB,MAAM,CAAC,aAAa,GAAG,IAAI,CAAC;IAC9B,CAAC;IAED,IAAI,SAAS,EAAE,CAAC;QACd,MAAM,CAAC,kBAAkB,GAAG,KAAK,CAAC,OAAO,CAAC,SAAS,CAAC;YAClD,CAAC,CAAC,SAAS;YACX,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,GAAG,CACtC,0CAA0C,EAC1C;QACE,MAAM,EAAE;YACN,IAAI,EAAE;gBACJ,kBAAkB,EAAE,iBAAiB;aACtC;YACD,KAAK,EAAE,MAAM;SACd;KACF,CACF,CAAC;IAEF,IAAI,KAAK;QAAE,MAAM,KAAK,CAAC;IACvB,OAAO;QACL,MAAM,EAAE,IAAI,EAAE,IAAI,IAAI,EAAE;QACxB,UAAU,EAAE,IAAI,EAAE,WAAW,IAAI,IAAI;KACtC,CAAC;AACJ,CAAC"}

package/dist/esm/traces/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./getTraces.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/traces/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/traces/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}

package/dist/esm/traces/index.js

@@ -0,0 +1,2 @@
+export * from "./getTraces.js";
+//# sourceMappingURL=index.js.map

package/dist/esm/traces/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/traces/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC"}