> ## 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. # Query reporting metrics > 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. ## OpenAPI ````yaml post /v2/reporting openapi: 3.1.0 info: title: orq.ai API version: '2.0' description: orq.ai API documentation servers: - url: https://api.orq.ai security: - ApiKey: [] tags: - description: List models available through the AI Router. name: Models - name: Guardrail Rules - name: Policies - name: Routing Rules - name: API keys description: >- API keys authenticate programmatic access to the workspace. The unified key model exposes opaque tokens, per-domain access grants, and budget / rate-limit constraints (see ADR 0001 and ADR 0002). - name: Budgets description: >- Budgets govern spend, token usage, and request rate across six scopes: workspace, project, identity, api-key, provider, and model. A budget is hierarchical and defense-in-depth — every applicable budget is a hard gate, and the most restrictive one wins per dimension (see ADR 0007). - name: Documentation description: >- Search the orq.ai documentation. Proxies the workspace's query to the hosted docs search index. - name: Files description: File upload and retrieval operations. - name: Identities description: >- Identities represent end users from your system for usage and engagement tracking. - name: Projects description: Projects organize resources within a workspace - name: Skills description: >- Skills are modular instructions you can use to codify processes and conventions - name: Responses - description: >- Run agents on a cadence — cron, interval, or one-off. Minimum firing interval is 1 hour. name: Agent Schedules - name: Embeddings - name: Reporting description: >- GenAI reporting API over canonical analytics rollups. Accepts a metric name, time range, grain, group-by, and filters; returns a typed time series and optional totals. externalDocs: url: https://docs.orq.ai description: orq.ai Documentation paths: /v2/reporting: post: tags: - Reporting summary: Query reporting metrics description: >- 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. operationId: ReportingQuery requestBody: content: application/json: schema: $ref: '#/components/schemas/QueryReportRequest' required: true responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/QueryReportResponse' components: schemas: QueryReportRequest: required: - metric - from - to type: object properties: metric: enum: - 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 type: string description: Catalogue metric to query. from: type: string description: Inclusive lower bound for the report window (RFC 3339, UTC). format: date-time to: type: string description: Exclusive upper bound for the report window (RFC 3339, UTC). format: date-time grain: enum: - auto - minute - hour - day type: string description: >- Requested bucket grain. Use `auto` or omit the field to let the server choose based on the requested range. group_by: type: array items: type: string enum: - 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 description: >- Reporting dimensions to break down by. Valid dimensions depend on the selected metric. filters: type: array items: $ref: '#/components/schemas/Filter' description: Up to 20 allowlisted predicates combined with AND. limit: type: integer description: |- Maximum bucket rows returned. Defaults to 1000 and is capped at 5000. format: int32 time_zone: type: string description: |- IANA time zone applied to bucket boundaries, for example `America/New_York`. Response timestamps remain UTC. Empty means UTC. include_totals: type: boolean description: |- When true, include a `totals` block aggregated across the full report window. QueryReportResponse: type: object properties: object: enum: - report type: string description: >- Object discriminator for typed SDKs and JSON parsers; always `report`. request: allOf: - $ref: '#/components/schemas/QueryReportRequest' description: |- The request that produced this response, parroted back so caller code never has to remember its own payload to interpret the result. data: type: array items: $ref: '#/components/schemas/DataPoint' description: Time-ordered buckets. totals: allOf: - $ref: '#/components/schemas/Totals' description: |- Totals across the whole window. Present only when `include_totals=true` on the request. has_more: type: boolean description: |- Pagination contract. Always populated; currently false because the server caps the response at `limit` instead of issuing cursors. meta: allOf: - $ref: '#/components/schemas/ResponseMeta' description: Diagnostic metadata. Filter: type: object properties: field: enum: - 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 type: string description: >- Public reporting dimension to filter on. Valid fields depend on the selected metric. op: enum: - eq - neq - in - not_in type: string description: >- Predicate operator. `eq` and `neq` accept exactly one value; `in` and `not_in` accept 1-100 values. values: type: array items: type: string description: |- Values compared against the selected field. Values are interpreted as public API strings, not SQL fragments. DataPoint: type: object properties: timestamp: type: string description: |- Bucket start in UTC, RFC 3339. Clients that need epoch ms can call `Date.parse(timestamp)` or `new Date(timestamp).getTime()` — returning the int64 in JSON would force a string (protojson rule) and force callers to coerce anyway, so we ship ISO only. format: date-time dimensions: type: object additionalProperties: type: string description: |- Public breakdown labels for this bucket, keyed by group-by column. Empty when no group-by was requested. Empty values are omitted so the caller never has to special-case `""`. metrics: type: object additionalProperties: type: number format: double description: |- Metric values for this bucket. Single-metric requests carry one entry keyed by the requested metric name (e.g. `"genai.cost"` → `0.000495`). Bundle metrics carry one entry per field. Numbers are pre-rounded to 10 significant digits to avoid IEEE-754 display noise like `0.00009900000000000001`. Totals: type: object properties: metrics: type: object additionalProperties: type: number format: double description: |- Same shape and rules as `DataPoint.metrics`, aggregated across the whole window. ResponseMeta: type: object properties: effective_grain: enum: - minute - hour - day type: string description: Bucket grain actually applied by the planner. row_count: type: integer description: |- Number of rows in `data`. Cheap hint for clients that paginate client-side; mirrors `len(data)`. format: int32 request_id: type: string description: |- Stable identifier for this query. Forward in support tickets so server logs can be correlated. Also returned in the `X-Request-Id` response header. currency: enum: - USD type: string description: ISO 4217 currency code for cost fields. Always `USD` today. warnings: type: array items: type: string description: >- Non-fatal warnings about the response. May contain `totals_unavailable` when totals were requested but failed. securitySchemes: ApiKey: type: http scheme: bearer bearerFormat: JWT ````