Reporting SDK Reference - Orq.ai Documentation

Reporting

Query Reports

Returns time-series, scalar, and top-list analytics for AI usage, cost, latency, evaluator results, and guardrail outcomes. This API remains supported while the neutral telemetry envelope is proven against every reporting request shape.

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)

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();

Show Parameters

{
    "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_": 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"]],  # 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"]],
}

{
  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";
}

Show Response

{
    "object": Optional[Literal["report"]],
    "data": [{  # optional
        "timestamp": date,  # 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
    },
}

{
  object?: "report";
  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[];
  };
}

⌘I