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

# Reporting SDK Reference

> Query analytics reports with the Node.js and Python SDKs: time-series and top-list data on AI usage, cost, latency, and evaluator results.

## Reporting

### Query Reports

Returns time-series, scalar, and top-list analytics for AI usage, cost, latency, evaluator results, and guardrail outcomes.

<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.reporting.query(metric="genai.evaluator.score.avg", from_=parse_datetime("2026-03-06T12:20:53.904Z"), to=parse_datetime("2026-12-14T22:21:09.964Z"))

      # 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.reporting.query({
      metric: "genai.evaluator.score.avg",
      from: new Date("2026-03-06T12:20:53.904Z"),
      to: new Date("2026-12-14T22:21:09.964Z"),
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "metric": Literal["genai.requests", "genai.tokens", "genai.cost", "genai.errors", "genai.error_rate", "genai.latency.p50", "genai.latency.p95", "genai.latency.p99", "genai.ttft.avg", "genai.ttft.p50", "genai.ttft.p95", "genai.evaluator.runs", "genai.evaluator.pass_rate", "genai.evaluator.score.avg", "genai.guardrail.runs", "genai.guardrail.block_rate", "genai.guardrail.triggered", "genai.usage"],  # required
        "from_": str,  # required
        "to": str,  # required
        "grain": Optional[Literal["auto", "minute", "hour", "day"]],
        "group_by": List[Literal["project", "identity", "provider", "model", "product", "api_key", "status_code", "http_status_code", "credential_type", "dimension", "dimension_type", "tag", "agent", "tool", "deployment", "evaluator", "dataset", "prompt", "policy", "conversation", "thread", "memory_store", "knowledge", "sheet", "guardrail_origin", "evaluator_name", "evaluator_type", "evaluator_version", "result_type", "evaluation_stage", "guardrail_stage", "evaluator_stage", "guardrail_action", "result_label"]],  # optional
        "filters": [{  # optional
            "field": Optional[Literal["project", "identity", "provider", "model", "product", "api_key", "status_code", "http_status_code", "credential_type", "billing_billable", "dimension", "dimension_type", "tag", "agent", "tool", "deployment", "evaluator", "dataset", "prompt", "policy", "conversation", "thread", "memory_store", "knowledge", "sheet", "guardrail_origin", "evaluator_name", "evaluator_type", "evaluator_version", "result_type", "evaluation_stage", "guardrail_stage", "evaluator_stage", "guardrail_action", "result_label"]],
            "op": Optional[Literal["eq", "neq", "in", "not_in"]],
            "values": List[str],  # optional
        }],
        "limit": Optional[int],
        "time_zone": Optional[str],
        "include_totals": Optional[bool],
        "mode": Optional[Literal["timeseries", "scalar"]],
        "sort": Optional[Literal["desc", "asc"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      metric: "genai.requests" | "genai.tokens" | "genai.cost" | "genai.errors" | "genai.error_rate" | "genai.latency.p50" | "genai.latency.p95" | "genai.latency.p99" | "genai.ttft.avg" | "genai.ttft.p50" | "genai.ttft.p95" | "genai.evaluator.runs" | "genai.evaluator.pass_rate" | "genai.evaluator.score.avg" | "genai.guardrail.runs" | "genai.guardrail.block_rate" | "genai.guardrail.triggered" | "genai.usage";  // required
      from: Date;  // required
      to: Date;  // required
      grain?: "auto" | "minute" | "hour" | "day";
      groupBy?: ("project" | "identity" | "provider" | "model" | "product" | "api_key" | "status_code" | "http_status_code" | "credential_type" | "dimension" | "dimension_type" | "tag" | "agent" | "tool" | "deployment" | "evaluator" | "dataset" | "prompt" | "policy" | "conversation" | "thread" | "memory_store" | "knowledge" | "sheet" | "guardrail_origin" | "evaluator_name" | "evaluator_type" | "evaluator_version" | "result_type" | "evaluation_stage" | "guardrail_stage" | "evaluator_stage" | "guardrail_action" | "result_label")[];
      filters?: {
        field?: "project" | "identity" | "provider" | "model" | "product" | "api_key" | "status_code" | "http_status_code" | "credential_type" | "billing_billable" | "dimension" | "dimension_type" | "tag" | "agent" | "tool" | "deployment" | "evaluator" | "dataset" | "prompt" | "policy" | "conversation" | "thread" | "memory_store" | "knowledge" | "sheet" | "guardrail_origin" | "evaluator_name" | "evaluator_type" | "evaluator_version" | "result_type" | "evaluation_stage" | "guardrail_stage" | "evaluator_stage" | "guardrail_action" | "result_label";
        op?: "eq" | "neq" | "in" | "not_in";
        values?: string[];
      }[];
      limit?: number;
      timeZone?: string;
      includeTotals?: boolean;
      mode?: "timeseries" | "scalar";
      sort?: "desc" | "asc";
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[Literal["report"]],
        "request": {  # optional
            "metric": Literal["genai.requests", "genai.tokens", "genai.cost", "genai.errors", "genai.error_rate", "genai.latency.p50", "genai.latency.p95", "genai.latency.p99", "genai.ttft.avg", "genai.ttft.p50", "genai.ttft.p95", "genai.evaluator.runs", "genai.evaluator.pass_rate", "genai.evaluator.score.avg", "genai.guardrail.runs", "genai.guardrail.block_rate", "genai.guardrail.triggered", "genai.usage"],
            "from_": str,
            "to": str,
            "grain": Optional[Literal["auto", "minute", "hour", "day"]],
            "group_by": List[Literal["project", "identity", "provider", "model", "product", "api_key", "status_code", "http_status_code", "credential_type", "dimension", "dimension_type", "tag", "agent", "tool", "deployment", "evaluator", "dataset", "prompt", "policy", "conversation", "thread", "memory_store", "knowledge", "sheet", "guardrail_origin", "evaluator_name", "evaluator_type", "evaluator_version", "result_type", "evaluation_stage", "guardrail_stage", "evaluator_stage", "guardrail_action", "result_label"]],  # optional
            "filters": [{  # optional
                "field": Optional[Literal["project", "identity", "provider", "model", "product", "api_key", "status_code", "http_status_code", "credential_type", "billing_billable", "dimension", "dimension_type", "tag", "agent", "tool", "deployment", "evaluator", "dataset", "prompt", "policy", "conversation", "thread", "memory_store", "knowledge", "sheet", "guardrail_origin", "evaluator_name", "evaluator_type", "evaluator_version", "result_type", "evaluation_stage", "guardrail_stage", "evaluator_stage", "guardrail_action", "result_label"]],
                "op": Optional[Literal["eq", "neq", "in", "not_in"]],
                "values": List[str],  # optional
            }],
            "limit": Optional[int],
            "time_zone": Optional[str],
            "include_totals": Optional[bool],
            "mode": Optional[Literal["timeseries", "scalar"]],
            "sort": Optional[Literal["desc", "asc"]],
        },
        "data": [{  # optional
            "timestamp": str,  # optional
            "dimensions": Dict[str, str],  # optional
            "metrics": Dict[str, float],  # optional
        }],
        "totals": {  # optional
            "metrics": Dict[str, float],  # optional
        },
        "has_more": Optional[bool],
        "meta": {  # optional
            "effective_grain": Optional[Literal["minute", "hour", "day"]],
            "row_count": Optional[int],
            "request_id": Optional[str],
            "currency": Optional[Literal["USD"]],
            "warnings": List[str],  # optional
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: "report";
      request?: {
        metric: "genai.requests" | "genai.tokens" | "genai.cost" | "genai.errors" | "genai.error_rate" | "genai.latency.p50" | "genai.latency.p95" | "genai.latency.p99" | "genai.ttft.avg" | "genai.ttft.p50" | "genai.ttft.p95" | "genai.evaluator.runs" | "genai.evaluator.pass_rate" | "genai.evaluator.score.avg" | "genai.guardrail.runs" | "genai.guardrail.block_rate" | "genai.guardrail.triggered" | "genai.usage";
        from: Date;
        to: Date;
        grain?: "auto" | "minute" | "hour" | "day";
        groupBy?: ("project" | "identity" | "provider" | "model" | "product" | "api_key" | "status_code" | "http_status_code" | "credential_type" | "dimension" | "dimension_type" | "tag" | "agent" | "tool" | "deployment" | "evaluator" | "dataset" | "prompt" | "policy" | "conversation" | "thread" | "memory_store" | "knowledge" | "sheet" | "guardrail_origin" | "evaluator_name" | "evaluator_type" | "evaluator_version" | "result_type" | "evaluation_stage" | "guardrail_stage" | "evaluator_stage" | "guardrail_action" | "result_label")[];
        filters?: {
          field?: "project" | "identity" | "provider" | "model" | "product" | "api_key" | "status_code" | "http_status_code" | "credential_type" | "billing_billable" | "dimension" | "dimension_type" | "tag" | "agent" | "tool" | "deployment" | "evaluator" | "dataset" | "prompt" | "policy" | "conversation" | "thread" | "memory_store" | "knowledge" | "sheet" | "guardrail_origin" | "evaluator_name" | "evaluator_type" | "evaluator_version" | "result_type" | "evaluation_stage" | "guardrail_stage" | "evaluator_stage" | "guardrail_action" | "result_label";
          op?: "eq" | "neq" | "in" | "not_in";
          values?: string[];
        }[];
        limit?: number;
        timeZone?: string;
        includeTotals?: boolean;
        mode?: "timeseries" | "scalar";
        sort?: "desc" | "asc";
      };
      data?: {
        timestamp?: Date;
        dimensions?: Record<string, string>;
        metrics?: Record<string, number>;
      }[];
      totals?: {
        metrics?: Record<string, number>;
      };
      hasMore?: boolean;
      meta?: {
        effectiveGrain?: "minute" | "hour" | "day";
        rowCount?: number;
        requestId?: string;
        currency?: "USD";
        warnings?: string[];
      };
    }
    ```
  </CodeGroup>
</Expandable>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.