> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Traces SDK Reference

> SDK reference for the Traces API, available in Node.js and Python.

## Traces

### Aggregate Traces

Aggregate trace metrics using the structured trace filter contract. This API remains supported; POST /v3/telemetry/query offers the same aggregate shape in a neutral multi-signal envelope.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.aggregate()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.aggregate({});

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "from_": date,  # optional
        "to": date,  # optional
        "filters": [{  # optional
            "field": Optional[str],
            "op": Optional[str],
            "values": List[str],  # optional
        }],
        "group_by": List[str],  # optional
        "compute": [{  # optional
            "metric": Optional[str],
            "op": Optional[str],
        }],
        "limit": Optional[int],
        "filter_operator": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      from?: Date;
      to?: Date;
      filters?: {
        field?: string;
        op?: string;
        values?: string[];
      }[];
      groupBy?: string[];
      compute?: {
        metric?: string;
        op?: string;
      }[];
      limit?: number;
      filterOperator?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[str],
        "data": [{  # optional
            "group": Dict[str, str],  # optional
            "metrics": Dict[str, float],  # optional
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: string;
      data?: {
        group?: Record<string, string>;
        metrics?: Record<string, number>;
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

### List Facets

List trace fields that support facet value discovery.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.list_facets()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.listFacets();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "data": [{  # optional
            "field": Optional[str],
            "label": Optional[str],
            "type": Optional[str],
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      data?: {
        field?: string;
        label?: string;
        type?: string;
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

### List Facet Values

List values and counts for one trace facet field.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.list_facet_values(field="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.listFacetValues({
      field: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "field": str,  # required
        "from_": date,  # optional
        "to": date,  # optional
        "limit": Optional[int],
        "filter_operator": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      field: string;  // required
      from?: Date;
      to?: Date;
      limit?: number;
      filterOperator?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "field": Optional[str],
        "values": [{  # optional
            "value": Optional[str],
            "count": Optional[int],
        }],
        "has_more": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      field?: string;
      values?: {
        value?: string;
        count?: number;
      }[];
      hasMore?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>

### List Fields

List currently supported static trace fields.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.list_fields()

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.listFields();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "data": [{  # optional
            "name": Optional[str],
            "label": Optional[str],
            "type": Optional[str],
            "scope": Optional[str],
            "match": Optional[str],
            "operators": List[str],  # optional
            "facet": Optional[bool],
            "sortable": Optional[bool],
            "groupable": Optional[bool],
            "aliases": List[str],  # optional
            "enum_values": List[str],  # optional
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      data?: {
        name?: string;
        label?: string;
        type?: string;
        scope?: string;
        match?: string;
        operators?: string[];
        facet?: boolean;
        sortable?: boolean;
        groupable?: boolean;
        aliases?: string[];
        enumValues?: string[];
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

### Query Traces

Run an OQL trace query. OQL is validated against the trace field registry and compiled through the trace planner.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  from orq_ai_sdk.utils import parse_datetime
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.query(from_=parse_datetime("2024-12-12T15:00:42.128Z"), to=parse_datetime("2025-02-10T08:55:05.233Z"), oql="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.query({
      from: new Date("2024-12-12T15:00:42.128Z"),
      to: new Date("2025-02-10T08:55:05.233Z"),
      oql: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "from_": date,  # required
        "to": date,  # required
        "oql": str,  # required
        "limit": Optional[int],
        "page_token": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      from: Date;  // required
      to: Date;  // required
      oql: string;  // required
      limit?: number;
      pageToken?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[str],
        "search": {  # optional
            "object": Optional[Literal["list"]],
            "data": [{  # optional
                "object": Optional[Literal["trace"]],
                "trace_id": Optional[str],
                "root_span_id": Optional[str],
                "leading_span_id": Optional[str],
                "name": Optional[str],
                "operation": Optional[str],
                "status": Optional[str],
                "started_at": date,  # optional
                "ended_at": date,  # optional
                "duration_ms": Optional[float],
                "project_id": Optional[str],
                "identity_id": Optional[str],
                "session_id": Optional[str],
                "thread_id": Optional[str],
                "product": Optional[str],
                "providers": List[str],  # optional
                "models": List[str],  # optional
                "agent": {  # optional
                    "id": Optional[str],
                    "name": Optional[str],
                },
                "usage": {  # optional
                    "prompt_tokens": Optional[int],
                    "completion_tokens": Optional[int],
                    "total_tokens": Optional[int],
                    "prompt_cached_tokens": Optional[int],
                    "prompt_audio_tokens": Optional[int],
                    "completion_reasoning_tokens": Optional[int],
                    "completion_audio_tokens": Optional[int],
                    "completion_accepted_prediction_tokens": Optional[int],
                    "completion_rejected_prediction_tokens": Optional[int],
                },
                "cost": {  # optional
                    "input": Optional[float],
                    "output": Optional[float],
                    "cache_read": Optional[float],
                    "cache_write": Optional[float],
                    "reasoning": Optional[float],
                    "web_search": Optional[float],
                    "total": Optional[float],
                    "currency": Optional[str],
                    "cached": Optional[float],
                    "audio_input": Optional[float],
                    "audio_output": Optional[float],
                    "accepted_prediction": Optional[float],
                    "rejected_prediction": Optional[float],
                    "billable": Optional[bool],
                    "pricing_tier": Optional[str],
                    "threshold_exceeded": Optional[bool],
                    "integration_id": Optional[str],
                },
                "id": Optional[str],
                "span_id": Optional[str],
                "parent_id": Optional[str],
                "type": Optional[str],
                "context": {  # optional
                    "trace_id": Optional[str],
                    "span_id": Optional[str],
                },
                "attributes": Dict[str, Any],  # optional
                "start_time": date,  # optional
                "end_time": date,  # optional
                "duration": Optional[float],
            }],
            "has_more": Optional[bool],
            "next_page_token": Optional[str],
            "meta": {  # optional
                "request_id": Optional[str],
                "from_": date,  # optional
                "to": date,  # optional
                "row_count": Optional[int],
            },
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: string;
      search?: {
        object?: "list";
        data?: {
          object?: "trace";
          traceId?: string;
          rootSpanId?: string;
          leadingSpanId?: string;
          name?: string;
          operation?: string;
          status?: string;
          startedAt?: Date;
          endedAt?: Date;
          durationMs?: number;
          projectId?: string;
          identityId?: string;
          sessionId?: string;
          threadId?: string;
          product?: string;
          providers?: string[];
          models?: string[];
          agent?: {
            id?: string;
            name?: string;
          };
          usage?: {
            promptTokens?: number;
            completionTokens?: number;
            totalTokens?: number;
            promptCachedTokens?: number;
            promptAudioTokens?: number;
            completionReasoningTokens?: number;
            completionAudioTokens?: number;
            completionAcceptedPredictionTokens?: number;
            completionRejectedPredictionTokens?: number;
          };
          cost?: {
            input?: number;
            output?: number;
            cacheRead?: number;
            cacheWrite?: number;
            reasoning?: number;
            webSearch?: number;
            total?: number;
            currency?: string;
            cached?: number;
            audioInput?: number;
            audioOutput?: number;
            acceptedPrediction?: number;
            rejectedPrediction?: number;
            billable?: boolean;
            pricingTier?: string;
            thresholdExceeded?: boolean;
            integrationId?: string;
          };
          id?: string;
          spanId?: string;
          parentId?: string;
          type?: string;
          context?: {
            traceId?: string;
            spanId?: string;
          };
          attributes?: Record<string, unknown>;
          startTime?: Date;
          endTime?: Date;
          duration?: number;
        }[];
        hasMore?: boolean;
        nextPageToken?: string;
        meta?: {
          requestId?: string;
          from?: Date;
          to?: Date;
          rowCount?: number;
        };
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Search Traces

Search trace summaries using the structured trace filter contract.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  from orq_ai_sdk.utils import parse_datetime
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.search(from_=parse_datetime("2025-05-02T22:00:26.030Z"), to=parse_datetime("2025-09-17T16:33:38.335Z"))

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.search({
      from: new Date("2025-05-02T22:00:26.030Z"),
      to: new Date("2025-09-17T16:33:38.335Z"),
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "from_": date,  # required
        "to": date,  # required
        "filters": [{  # optional
            "field": Optional[str],
            "op": Optional[str],
            "values": List[str],  # optional
        }],
        "filter_operator": Optional[str],
        "query": Optional[str],
        "sort": [{  # optional
            "field": Optional[str],
            "order": Optional[str],
        }],
        "limit": Optional[int],
        "page_token": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      from: Date;  // required
      to: Date;  // required
      filters?: {
        field?: string;
        op?: string;
        values?: string[];
      }[];
      filterOperator?: string;
      query?: string;
      sort?: {
        field?: string;
        order?: string;
      }[];
      limit?: number;
      pageToken?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[Literal["list"]],
        "data": [{  # optional
            "object": Optional[Literal["trace"]],
            "trace_id": Optional[str],
            "root_span_id": Optional[str],
            "leading_span_id": Optional[str],
            "name": Optional[str],
            "operation": Optional[str],
            "status": Optional[str],
            "started_at": date,  # optional
            "ended_at": date,  # optional
            "duration_ms": Optional[float],
            "project_id": Optional[str],
            "identity_id": Optional[str],
            "session_id": Optional[str],
            "thread_id": Optional[str],
            "product": Optional[str],
            "providers": List[str],  # optional
            "models": List[str],  # optional
            "agent": {  # optional
                "id": Optional[str],
                "name": Optional[str],
            },
            "usage": {  # optional
                "prompt_tokens": Optional[int],
                "completion_tokens": Optional[int],
                "total_tokens": Optional[int],
                "prompt_cached_tokens": Optional[int],
                "prompt_audio_tokens": Optional[int],
                "completion_reasoning_tokens": Optional[int],
                "completion_audio_tokens": Optional[int],
                "completion_accepted_prediction_tokens": Optional[int],
                "completion_rejected_prediction_tokens": Optional[int],
            },
            "cost": {  # optional
                "input": Optional[float],
                "output": Optional[float],
                "cache_read": Optional[float],
                "cache_write": Optional[float],
                "reasoning": Optional[float],
                "web_search": Optional[float],
                "total": Optional[float],
                "currency": Optional[str],
                "cached": Optional[float],
                "audio_input": Optional[float],
                "audio_output": Optional[float],
                "accepted_prediction": Optional[float],
                "rejected_prediction": Optional[float],
                "billable": Optional[bool],
                "pricing_tier": Optional[str],
                "threshold_exceeded": Optional[bool],
                "integration_id": Optional[str],
            },
            "id": Optional[str],
            "span_id": Optional[str],
            "parent_id": Optional[str],
            "type": Optional[str],
            "context": {  # optional
                "trace_id": Optional[str],
                "span_id": Optional[str],
            },
            "attributes": Dict[str, Any],  # optional
            "start_time": date,  # optional
            "end_time": date,  # optional
            "duration": Optional[float],
        }],
        "has_more": Optional[bool],
        "next_page_token": Optional[str],
        "meta": {  # optional
            "request_id": Optional[str],
            "from_": date,  # optional
            "to": date,  # optional
            "row_count": Optional[int],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: "list";
      data?: {
        object?: "trace";
        traceId?: string;
        rootSpanId?: string;
        leadingSpanId?: string;
        name?: string;
        operation?: string;
        status?: string;
        startedAt?: Date;
        endedAt?: Date;
        durationMs?: number;
        projectId?: string;
        identityId?: string;
        sessionId?: string;
        threadId?: string;
        product?: string;
        providers?: string[];
        models?: string[];
        agent?: {
          id?: string;
          name?: string;
        };
        usage?: {
          promptTokens?: number;
          completionTokens?: number;
          totalTokens?: number;
          promptCachedTokens?: number;
          promptAudioTokens?: number;
          completionReasoningTokens?: number;
          completionAudioTokens?: number;
          completionAcceptedPredictionTokens?: number;
          completionRejectedPredictionTokens?: number;
        };
        cost?: {
          input?: number;
          output?: number;
          cacheRead?: number;
          cacheWrite?: number;
          reasoning?: number;
          webSearch?: number;
          total?: number;
          currency?: string;
          cached?: number;
          audioInput?: number;
          audioOutput?: number;
          acceptedPrediction?: number;
          rejectedPrediction?: number;
          billable?: boolean;
          pricingTier?: string;
          thresholdExceeded?: boolean;
          integrationId?: string;
        };
        id?: string;
        spanId?: string;
        parentId?: string;
        type?: string;
        context?: {
          traceId?: string;
          spanId?: string;
        };
        attributes?: Record<string, unknown>;
        startTime?: Date;
        endTime?: Date;
        duration?: number;
      }[];
      hasMore?: boolean;
      nextPageToken?: string;
      meta?: {
        requestId?: string;
        from?: Date;
        to?: Date;
        rowCount?: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Trace

Retrieve one trace summary by trace id.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.get(trace_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.get({
      traceId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "trace_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      traceId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "trace": {  # optional
            "object": Optional[Literal["trace"]],
            "trace_id": Optional[str],
            "root_span_id": Optional[str],
            "leading_span_id": Optional[str],
            "name": Optional[str],
            "operation": Optional[str],
            "status": Optional[str],
            "started_at": date,  # optional
            "ended_at": date,  # optional
            "duration_ms": Optional[float],
            "project_id": Optional[str],
            "identity_id": Optional[str],
            "session_id": Optional[str],
            "thread_id": Optional[str],
            "product": Optional[str],
            "providers": List[str],  # optional
            "models": List[str],  # optional
            "agent": {  # optional
                "id": Optional[str],
                "name": Optional[str],
            },
            "usage": {  # optional
                "prompt_tokens": Optional[int],
                "completion_tokens": Optional[int],
                "total_tokens": Optional[int],
                "prompt_cached_tokens": Optional[int],
                "prompt_audio_tokens": Optional[int],
                "completion_reasoning_tokens": Optional[int],
                "completion_audio_tokens": Optional[int],
                "completion_accepted_prediction_tokens": Optional[int],
                "completion_rejected_prediction_tokens": Optional[int],
            },
            "cost": {  # optional
                "input": Optional[float],
                "output": Optional[float],
                "cache_read": Optional[float],
                "cache_write": Optional[float],
                "reasoning": Optional[float],
                "web_search": Optional[float],
                "total": Optional[float],
                "currency": Optional[str],
                "cached": Optional[float],
                "audio_input": Optional[float],
                "audio_output": Optional[float],
                "accepted_prediction": Optional[float],
                "rejected_prediction": Optional[float],
                "billable": Optional[bool],
                "pricing_tier": Optional[str],
                "threshold_exceeded": Optional[bool],
                "integration_id": Optional[str],
            },
            "id": Optional[str],
            "span_id": Optional[str],
            "parent_id": Optional[str],
            "type": Optional[str],
            "context": {  # optional
                "trace_id": Optional[str],
                "span_id": Optional[str],
            },
            "attributes": Dict[str, Any],  # optional
            "start_time": date,  # optional
            "end_time": date,  # optional
            "duration": Optional[float],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      trace?: {
        object?: "trace";
        traceId?: string;
        rootSpanId?: string;
        leadingSpanId?: string;
        name?: string;
        operation?: string;
        status?: string;
        startedAt?: Date;
        endedAt?: Date;
        durationMs?: number;
        projectId?: string;
        identityId?: string;
        sessionId?: string;
        threadId?: string;
        product?: string;
        providers?: string[];
        models?: string[];
        agent?: {
          id?: string;
          name?: string;
        };
        usage?: {
          promptTokens?: number;
          completionTokens?: number;
          totalTokens?: number;
          promptCachedTokens?: number;
          promptAudioTokens?: number;
          completionReasoningTokens?: number;
          completionAudioTokens?: number;
          completionAcceptedPredictionTokens?: number;
          completionRejectedPredictionTokens?: number;
        };
        cost?: {
          input?: number;
          output?: number;
          cacheRead?: number;
          cacheWrite?: number;
          reasoning?: number;
          webSearch?: number;
          total?: number;
          currency?: string;
          cached?: number;
          audioInput?: number;
          audioOutput?: number;
          acceptedPrediction?: number;
          rejectedPrediction?: number;
          billable?: boolean;
          pricingTier?: string;
          thresholdExceeded?: boolean;
          integrationId?: string;
        };
        id?: string;
        spanId?: string;
        parentId?: string;
        type?: string;
        context?: {
          traceId?: string;
          spanId?: string;
        };
        attributes?: Record<string, unknown>;
        startTime?: Date;
        endTime?: Date;
        duration?: number;
      };
    }
    ```
  </CodeGroup>
</Expandable>

### List Spans

List canonical span summaries for a trace.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.list_spans(trace_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.listSpans({
      traceId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "trace_id": str,  # required
        "limit": Optional[int],
        "page_token": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      traceId: string;  // required
      limit?: number;
      pageToken?: string;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[str],
        "data": [{  # optional
            "object": Optional[str],
            "trace_id": Optional[str],
            "span_id": Optional[str],
            "parent_span_id": Optional[str],
            "name": Optional[str],
            "type": Optional[str],
            "operation": Optional[str],
            "status": Optional[str],
            "started_at": date,  # optional
            "ended_at": date,  # optional
            "duration_ms": Optional[float],
            "provider": Optional[str],
            "model": Optional[str],
            "usage": {  # optional
                "prompt_tokens": Optional[int],
                "completion_tokens": Optional[int],
                "total_tokens": Optional[int],
                "prompt_cached_tokens": Optional[int],
                "prompt_audio_tokens": Optional[int],
                "completion_reasoning_tokens": Optional[int],
                "completion_audio_tokens": Optional[int],
                "completion_accepted_prediction_tokens": Optional[int],
                "completion_rejected_prediction_tokens": Optional[int],
            },
            "cost": {  # optional
                "input": Optional[float],
                "output": Optional[float],
                "cache_read": Optional[float],
                "cache_write": Optional[float],
                "reasoning": Optional[float],
                "web_search": Optional[float],
                "total": Optional[float],
                "currency": Optional[str],
                "cached": Optional[float],
                "audio_input": Optional[float],
                "audio_output": Optional[float],
                "accepted_prediction": Optional[float],
                "rejected_prediction": Optional[float],
                "billable": Optional[bool],
                "pricing_tier": Optional[str],
                "threshold_exceeded": Optional[bool],
                "integration_id": Optional[str],
            },
            "has_detail": Optional[bool],
        }],
        "has_more": Optional[bool],
        "next_page_token": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: string;
      data?: {
        object?: string;
        traceId?: string;
        spanId?: string;
        parentSpanId?: string;
        name?: string;
        type?: string;
        operation?: string;
        status?: string;
        startedAt?: Date;
        endedAt?: Date;
        durationMs?: number;
        provider?: string;
        model?: string;
        usage?: {
          promptTokens?: number;
          completionTokens?: number;
          totalTokens?: number;
          promptCachedTokens?: number;
          promptAudioTokens?: number;
          completionReasoningTokens?: number;
          completionAudioTokens?: number;
          completionAcceptedPredictionTokens?: number;
          completionRejectedPredictionTokens?: number;
        };
        cost?: {
          input?: number;
          output?: number;
          cacheRead?: number;
          cacheWrite?: number;
          reasoning?: number;
          webSearch?: number;
          total?: number;
          currency?: string;
          cached?: number;
          audioInput?: number;
          audioOutput?: number;
          acceptedPrediction?: number;
          rejectedPrediction?: number;
          billable?: boolean;
          pricingTier?: string;
          thresholdExceeded?: boolean;
          integrationId?: string;
        };
        hasDetail?: boolean;
      }[];
      hasMore?: boolean;
      nextPageToken?: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Get Span

Retrieve one hydrated span.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.traces.get_span(trace_id="<id>", span_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.traces.getSpan({
      traceId: "<id>",
      spanId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "trace_id": str,  # required
        "span_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      traceId: string;  // required
      spanId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "span": {  # optional
            "summary": {  # optional
                "object": Optional[str],
                "trace_id": Optional[str],
                "span_id": Optional[str],
                "parent_span_id": Optional[str],
                "name": Optional[str],
                "type": Optional[str],
                "operation": Optional[str],
                "status": Optional[str],
                "started_at": date,  # optional
                "ended_at": date,  # optional
                "duration_ms": Optional[float],
                "provider": Optional[str],
                "model": Optional[str],
                "usage": {  # optional
                    "prompt_tokens": Optional[int],
                    "completion_tokens": Optional[int],
                    "total_tokens": Optional[int],
                    "prompt_cached_tokens": Optional[int],
                    "prompt_audio_tokens": Optional[int],
                    "completion_reasoning_tokens": Optional[int],
                    "completion_audio_tokens": Optional[int],
                    "completion_accepted_prediction_tokens": Optional[int],
                    "completion_rejected_prediction_tokens": Optional[int],
                },
                "cost": {  # optional
                    "input": Optional[float],
                    "output": Optional[float],
                    "cache_read": Optional[float],
                    "cache_write": Optional[float],
                    "reasoning": Optional[float],
                    "web_search": Optional[float],
                    "total": Optional[float],
                    "currency": Optional[str],
                    "cached": Optional[float],
                    "audio_input": Optional[float],
                    "audio_output": Optional[float],
                    "accepted_prediction": Optional[float],
                    "rejected_prediction": Optional[float],
                    "billable": Optional[bool],
                    "pricing_tier": Optional[str],
                    "threshold_exceeded": Optional[bool],
                    "integration_id": Optional[str],
                },
                "has_detail": Optional[bool],
            },
            "attributes": Dict[str, Any],  # optional
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      span?: {
        summary?: {
          object?: string;
          traceId?: string;
          spanId?: string;
          parentSpanId?: string;
          name?: string;
          type?: string;
          operation?: string;
          status?: string;
          startedAt?: Date;
          endedAt?: Date;
          durationMs?: number;
          provider?: string;
          model?: string;
          usage?: {
            promptTokens?: number;
            completionTokens?: number;
            totalTokens?: number;
            promptCachedTokens?: number;
            promptAudioTokens?: number;
            completionReasoningTokens?: number;
            completionAudioTokens?: number;
            completionAcceptedPredictionTokens?: number;
            completionRejectedPredictionTokens?: number;
          };
          cost?: {
            input?: number;
            output?: number;
            cacheRead?: number;
            cacheWrite?: number;
            reasoning?: number;
            webSearch?: number;
            total?: number;
            currency?: string;
            cached?: number;
            audioInput?: number;
            audioOutput?: number;
            acceptedPrediction?: number;
            rejectedPrediction?: number;
            billable?: boolean;
            pricingTier?: string;
            thresholdExceeded?: boolean;
            integrationId?: string;
          };
          hasDetail?: boolean;
        };
        attributes?: Record<string, unknown>;
      };
    }
    ```
  </CodeGroup>
</Expandable>