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

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

## Reporting

### Query Reports

Returns time-series analytics for AI usage, cost, latency, evaluator results, and guardrail outcomes. Select a metric and time range, break results down by supported dimensions, apply filters, and optionally include totals for the full range.

<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.latency.p50", "genai.latency.p95", "genai.latency.p99", "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": 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"]],
        "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],
        },
        "limit": Optional[int],
        "time_zone": Optional[str],
        "include_totals": Optional[bool],
    }
    ```

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

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "object": Optional[Literal["report"]],
        "data": {  # optional
            "timestamp": date,
            "dimensions": Dict[str, str],
            "metrics": Dict[str, float],
        },
        "totals": {  # optional
            "metrics": Dict[str, float],
        },
        "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],
        },
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      object?: string;
      data?: {
        timestamp?: Date;
        dimensions?: Record<string, string>;
        metrics?: Record<string, number>;
      };
      totals?: {
        metrics?: Record<string, number>;
      };
      hasMore?: boolean;
      meta?: {
        effectiveGrain?: string;
        rowCount?: number;
        requestId?: string;
        currency?: string;
        warnings?: string[];
      };
    }
    ```
  </CodeGroup>
</Expandable>