> ## 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.

# Telemetry SDK Reference

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

## Telemetry

### List Capabilities

Lists the caller-scoped metrics, operations, units, query modes, result kinds, dimensions, and filter operators supported by the unified telemetry query service.

<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.telemetry.list_capabilities()

      # 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.telemetry.listCapabilities();

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "source": Optional[Literal["TELEMETRY_SOURCE_UNSPECIFIED", "TELEMETRY_SOURCE_TRACES", "TELEMETRY_SOURCE_METRICS", "TELEMETRY_SOURCE_LOGS"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      source?: "TELEMETRY_SOURCE_UNSPECIFIED" | "TELEMETRY_SOURCE_TRACES" | "TELEMETRY_SOURCE_METRICS" | "TELEMETRY_SOURCE_LOGS";
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "sources": [{  # optional
            "source": Optional[Literal["TELEMETRY_SOURCE_UNSPECIFIED", "TELEMETRY_SOURCE_TRACES", "TELEMETRY_SOURCE_METRICS", "TELEMETRY_SOURCE_LOGS"]],
            "label": Optional[str],
            "metrics": [{  # optional
                "name": Optional[str],
                "label": Optional[str],
                "description": Optional[str],
                "unit": Optional[str],
                "operations": List[str],  # optional
                "default_operation": Optional[str],
                "modes": List[Literal["TELEMETRY_QUERY_MODE_UNSPECIFIED", "TELEMETRY_QUERY_MODE_SCALAR", "TELEMETRY_QUERY_MODE_TIME_SERIES"]],  # optional
                "result_kinds": List[Literal["TELEMETRY_RESULT_KIND_UNSPECIFIED", "TELEMETRY_RESULT_KIND_SCALAR", "TELEMETRY_RESULT_KIND_GROUPED_SCALAR", "TELEMETRY_RESULT_KIND_TIME_SERIES", "TELEMETRY_RESULT_KIND_GROUPED_TIME_SERIES"]],  # optional
                "value_cardinality": Optional[Literal["TELEMETRY_VALUE_CARDINALITY_UNSPECIFIED", "TELEMETRY_VALUE_CARDINALITY_SINGLE", "TELEMETRY_VALUE_CARDINALITY_MULTIPLE"]],
                "dimensions": [{  # optional
                    "name": Optional[str],
                    "label": Optional[str],
                    "type": Optional[str],
                    "groupable": Optional[bool],
                    "filter_operators": List[str],  # optional
                    "key_prefix": Optional[str],
                }],
                "dimension_sets": [{  # optional
                    "name": Optional[str],
                    "group_by": List[str],  # optional
                    "filters": List[str],  # optional
                }],
            }],
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      sources?: {
        source?: "TELEMETRY_SOURCE_UNSPECIFIED" | "TELEMETRY_SOURCE_TRACES" | "TELEMETRY_SOURCE_METRICS" | "TELEMETRY_SOURCE_LOGS";
        label?: string;
        metrics?: {
          name?: string;
          label?: string;
          description?: string;
          unit?: string;
          operations?: string[];
          defaultOperation?: string;
          modes?: ("TELEMETRY_QUERY_MODE_UNSPECIFIED" | "TELEMETRY_QUERY_MODE_SCALAR" | "TELEMETRY_QUERY_MODE_TIME_SERIES")[];
          resultKinds?: ("TELEMETRY_RESULT_KIND_UNSPECIFIED" | "TELEMETRY_RESULT_KIND_SCALAR" | "TELEMETRY_RESULT_KIND_GROUPED_SCALAR" | "TELEMETRY_RESULT_KIND_TIME_SERIES" | "TELEMETRY_RESULT_KIND_GROUPED_TIME_SERIES")[];
          valueCardinality?: "TELEMETRY_VALUE_CARDINALITY_UNSPECIFIED" | "TELEMETRY_VALUE_CARDINALITY_SINGLE" | "TELEMETRY_VALUE_CARDINALITY_MULTIPLE";
          dimensions?: {
            name?: string;
            label?: string;
            type?: string;
            groupable?: boolean;
            filterOperators?: string[];
            keyPrefix?: string;
          }[];
          dimensionSets?: {
            name?: string;
            groupBy?: string[];
            filters?: string[];
          }[];
        }[];
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

### List Facet Values

Lists caller-scoped values for one source, metric, and field while applying sibling structured filters. Reporting metrics use metric-aware rollups; raw trace metrics preserve trace facet semantics.

<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.telemetry.list_facet_values(source="TELEMETRY_SOURCE_TRACES")

      # 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.telemetry.listFacetValues({ source: "TELEMETRY_SOURCE_TRACES" });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

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

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      source?: "TELEMETRY_SOURCE_UNSPECIFIED" | "TELEMETRY_SOURCE_TRACES" | "TELEMETRY_SOURCE_METRICS" | "TELEMETRY_SOURCE_LOGS";
      metric?: string;
      field?: string;
      from?: Date;
      to?: Date;
      filters?: {
        field?: string;
        op?: string;
        values?: string[];
      }[];
      filterOperator?: string;
      limit?: number;
    }
    ```
  </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>

### Query Telemetry

Canonical neutral query envelope for traces, metrics, and logs. Select a source, compute list, and time range; optionally group, filter, bucket, sort, limit, and include totals. ReportingService.QueryReport and TraceQueryService.AggregateTraces remain supported compatibility contracts.

<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.telemetry.query(source="TELEMETRY_SOURCE_TRACES")

      # 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.telemetry.query({ source: "TELEMETRY_SOURCE_TRACES" });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "source": Optional[Literal["TELEMETRY_SOURCE_UNSPECIFIED", "TELEMETRY_SOURCE_TRACES", "TELEMETRY_SOURCE_METRICS", "TELEMETRY_SOURCE_LOGS"]],
        "from_": str,  # optional
        "to": str,  # optional
        "compute": [{  # optional
            "metric": Optional[str],
            "op": Optional[str],
        }],
        "grain": Optional[str],
        "group_by": List[str],  # optional
        "filters": [{  # optional
            "field": Optional[str],
            "op": Optional[str],
            "values": List[str],  # optional
        }],
        "filter_operator": Optional[str],
        "limit": Optional[int],
        "time_zone": Optional[str],
        "include_totals": Optional[bool],
        "mode": Optional[Literal["timeseries", "scalar"]],
        "sort": Optional[Literal["desc", "asc"]],
        "interval_seconds": Optional[int],
        "selected_range_seconds": Optional[int],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      source?: "TELEMETRY_SOURCE_UNSPECIFIED" | "TELEMETRY_SOURCE_TRACES" | "TELEMETRY_SOURCE_METRICS" | "TELEMETRY_SOURCE_LOGS";
      from?: Date;
      to?: Date;
      compute?: {
        metric?: string;
        op?: string;
      }[];
      grain?: string;
      groupBy?: string[];
      filters?: {
        field?: string;
        op?: string;
        values?: string[];
      }[];
      filterOperator?: string;
      limit?: number;
      timeZone?: string;
      includeTotals?: boolean;
      mode?: "timeseries" | "scalar";
      sort?: "desc" | "asc";
      intervalSeconds?: number;
      selectedRangeSeconds?: number;
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[str],
        "data": [{  # optional
            "timestamp": str,  # optional
            "group": Dict[str, str],  # optional
            "metrics": Dict[str, float],  # optional
        }],
        "totals": {  # optional
            "timestamp": str,  # optional
            "group": Dict[str, str],  # optional
            "metrics": Dict[str, float],  # optional
        },
        "meta": {  # optional
            "effective_grain": Optional[str],
            "warnings": List[str],  # optional
            "row_count": Optional[int],
            "request_id": Optional[str],
            "currency": Optional[str],
        },
        "request": {  # optional
            "source": Optional[Literal["TELEMETRY_SOURCE_UNSPECIFIED", "TELEMETRY_SOURCE_TRACES", "TELEMETRY_SOURCE_METRICS", "TELEMETRY_SOURCE_LOGS"]],
            "from_": str,  # optional
            "to": str,  # optional
            "compute": [{  # optional
                "metric": Optional[str],
                "op": Optional[str],
            }],
            "grain": Optional[str],
            "group_by": List[str],  # optional
            "filters": [{  # optional
                "field": Optional[str],
                "op": Optional[str],
                "values": List[str],  # optional
            }],
            "filter_operator": Optional[str],
            "limit": Optional[int],
            "time_zone": Optional[str],
            "include_totals": Optional[bool],
            "mode": Optional[Literal["timeseries", "scalar"]],
            "sort": Optional[Literal["desc", "asc"]],
            "interval_seconds": Optional[int],
            "selected_range_seconds": Optional[int],
        },
        "has_more": Optional[bool],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: string;
      data?: {
        timestamp?: Date;
        group?: Record<string, string>;
        metrics?: Record<string, number>;
      }[];
      totals?: {
        timestamp?: Date;
        group?: Record<string, string>;
        metrics?: Record<string, number>;
      };
      meta?: {
        effectiveGrain?: string;
        warnings?: string[];
        rowCount?: number;
        requestId?: string;
        currency?: string;
      };
      request?: {
        source?: "TELEMETRY_SOURCE_UNSPECIFIED" | "TELEMETRY_SOURCE_TRACES" | "TELEMETRY_SOURCE_METRICS" | "TELEMETRY_SOURCE_LOGS";
        from?: Date;
        to?: Date;
        compute?: {
          metric?: string;
          op?: string;
        }[];
        grain?: string;
        groupBy?: string[];
        filters?: {
          field?: string;
          op?: string;
          values?: string[];
        }[];
        filterOperator?: string;
        limit?: number;
        timeZone?: string;
        includeTotals?: boolean;
        mode?: "timeseries" | "scalar";
        sort?: "desc" | "asc";
        intervalSeconds?: number;
        selectedRangeSeconds?: number;
      };
      hasMore?: boolean;
    }
    ```
  </CodeGroup>
</Expandable>