> ## 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 API | Query AI analytics

> Use the Orq.ai Reporting API for programmatic access to AI usage, cost, latency, token, evaluator, and guardrail analytics, broken down by any dimension.

Query AI usage, cost, latency, [Evaluator](/docs/evaluators/build) outcomes, and guardrail metrics programmatically. The **Reporting API** returns time-series data sliced by model, provider, project, identity, and more in a single JSON request.

<CardGroup cols={2}>
  <Card title="Spend dashboards" icon="dollar-sign" href="#metric-catalog">
    Track cost by model, provider, project, or credential type. Build per-customer billing breakdowns.
  </Card>

  <Card title="Performance monitoring" icon="gauge-high" href="#metric-catalog">
    Monitor p50, p95, and p99 latency over time across models and providers.
  </Card>

  <Card title="Evaluator quality" icon="badge-check" href="#metric-catalog">
    Quantify pass rate, average score, and result distribution per [**Evaluator**](/docs/evaluators/build) and version.
  </Card>

  <Card title="Guardrail enforcement" icon="shield-halved" href="#metric-catalog">
    Measure block rate, triggers, and outcomes by **Policy** and stage.
  </Card>
</CardGroup>

## Endpoint

<Badge color="blue">POST</Badge> `https://api.orq.ai/v2/reporting`

* All requests require a `Bearer` token. See [API Keys](/docs/ai-gateway/api-keys) for how to generate one.
* The workspace and project scope are derived from the API key itself.

<Note>
  Trace events flow into reporting in near real time, with a small ingestion delay measured in seconds. Queries against very recent windows may not yet include the latest events.
</Note>

<Card title="See the API Reference" icon="code" href="/reference/reporting/query-a-genai-report" horizontal>
  Interactive playground and full schema for `POST /v2/reporting`.
</Card>

## Quickstart

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.orq.ai/v2/reporting" \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "metric": "genai.usage",
      "from": "2026-05-01T00:00:00Z",
      "to":   "2026-05-15T00:00:00Z",
      "grain": "day",
      "group_by": ["model"],
      "include_totals": true
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({ apiKey: process.env.ORQ_API_KEY! });

  const report = await orq.reporting.query({
    metric: "genai.usage",
    from: new Date("2026-05-01T00:00:00Z"),
    to: new Date("2026-05-15T00:00:00Z"),
    grain: "day",
    groupBy: ["model"],
    includeTotals: true,
  });

  for (const row of report.data) {
    console.log(
      row.dimensions.model,
      row.metrics.total_cost,
      row.metrics.request_count,
    );
  }
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os

  from orq_ai_sdk import Orq

  orq = Orq(api_key=os.environ["ORQ_API_KEY"])

  report = orq.reporting.query(
      metric="genai.usage",
      from_="2026-05-01T00:00:00Z",
      to="2026-05-15T00:00:00Z",
      grain="day",
      group_by=["model"],
      include_totals=True,
  )

  for row in report.data:
      print(
          row.dimensions["model"],
          row.metrics["total_cost"],
          row.metrics["request_count"],
      )
  ```
</CodeGroup>

## Request

<Note>
  The wire format is **snake\_case** end-to-end. SDKs expose the same fields in each language's native style (`groupBy` in **TypeScript**, `group_by` in **Python**).
</Note>

<CodeGroup>
  ```json JSON theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "metric": "genai.usage",
    "from": "2026-05-01T00:00:00Z",
    "to": "2026-05-15T00:00:00Z",
    "grain": "day",
    "group_by": ["model", "provider"],
    "filters": [
      { "field": "project", "op": "eq", "values": ["proj_123"] }
    ],
    "include_totals": true,
    "limit": 1000,
    "time_zone": "UTC"
  }
  ```

  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api.orq.ai/v2/reporting" \
    -H "Authorization: Bearer $ORQ_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "metric": "genai.usage",
      "from": "2026-05-01T00:00:00Z",
      "to": "2026-05-15T00:00:00Z",
      "grain": "day",
      "group_by": ["model", "provider"],
      "filters": [
        { "field": "project", "op": "eq", "values": ["proj_123"] }
      ],
      "include_totals": true,
      "limit": 1000,
      "time_zone": "UTC"
    }'
  ```

  ```typescript TypeScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({ apiKey: process.env.ORQ_API_KEY! });

  const report = await orq.reporting.query({
    metric: "genai.usage",
    from: new Date("2026-05-01T00:00:00Z"),
    to: new Date("2026-05-15T00:00:00Z"),
    grain: "day",
    groupBy: ["model", "provider"],
    filters: [
      { field: "project", op: "eq", values: ["proj_123"] }
    ],
    includeTotals: true,
    limit: 1000,
    timeZone: "UTC",
  });
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os
  from orq_ai_sdk import Orq

  orq = Orq(api_key=os.environ["ORQ_API_KEY"])

  report = orq.reporting.query(
      metric="genai.usage",
      from_="2026-05-01T00:00:00Z",
      to="2026-05-15T00:00:00Z",
      grain="day",
      group_by=["model", "provider"],
      filters=[
          {"field": "project", "op": "eq", "values": ["proj_123"]}
      ],
      include_totals=True,
      limit=1000,
      time_zone="UTC",
  )
  ```
</CodeGroup>

<Info>
  See the [API reference](/reference/reporting/query-a-genai-report) for the full field schema, types, defaults, and validation rules.
</Info>

## Response

Every successful response follows the same envelope.

The `data` array contains time-ordered buckets. Each bucket carries:

* a `dimensions` map: the `group_by` values for that row (see [Dimensions](#dimensions))
* a `metrics` map: shape depends on the metric requested

**Scalar metrics** return a single named value per bucket. **Bundle metrics** (such as `genai.usage`) return a full set of related fields in one call.

`totals` is present only when `include_totals: true` is set in the request; otherwise the field is omitted. Metric values are rounded to 10 decimal places server-side.

<CodeGroup>
  ```json Response envelope (with totals) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "object": "report",
    "request": { },
    "data": [
      {
        "timestamp": "2026-05-01T00:00:00Z",
        "dimensions": { "model": "gpt-4o-mini", "provider": "openai" },
        "metrics": { }
      }
    ],
    "totals": {
      "metrics": { }
    },
    "has_more": false,
    "meta": {
      "effective_grain": "day",
      "row_count": 14,
      "request_id": "req_...",
      "currency": "USD"
    }
  }
  ```

  ```json Scalar metric theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "object": "report",
    "request": {
      "metric": "genai.cost",
      "from": "2026-05-14T00:00:00Z",
      "to": "2026-05-16T00:00:00Z",
      "grain": "day",
      "group_by": ["model"],
      "include_totals": false
    },
    "data": [
      {
        "timestamp": "2026-05-14T00:00:00Z",
        "dimensions": { "model": "gpt-4o-mini" },
        "metrics": { "genai.cost": 0.000225 }
      }
    ],
    "has_more": false,
    "meta": {
      "effective_grain": "day",
      "row_count": 1,
      "request_id": "req_...",
      "currency": "USD"
    }
  }
  ```

  ```json Bundle metric (genai.usage) theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "object": "report",
    "request": {
      "metric": "genai.usage",
      "from": "2026-05-14T00:00:00Z",
      "to": "2026-05-15T00:00:00Z",
      "grain": "day",
      "group_by": ["model"],
      "include_totals": false
    },
    "data": [
      {
        "timestamp": "2026-05-14T00:00:00Z",
        "dimensions": { "model": "gpt-4o-mini" },
        "metrics": {
          "request_count": 44,
          "error_count": 0,
          "input_tokens": 660,
          "output_tokens": 660,
          "total_tokens": 1320,
          "cached_input_tokens": 0,
          "reasoning_tokens": 0,
          "audio_input_tokens": 0,
          "audio_output_tokens": 0,
          "total_cost": 0.000495,
          "input_cost": 0.000099,
          "output_cost": 0.000396,
          "cached_cost": 0,
          "reasoning_cost": 0
        }
      }
    ],
    "has_more": false,
    "meta": {
      "effective_grain": "day",
      "row_count": 1,
      "request_id": "req_...",
      "currency": "USD"
    }
  }
  ```
</CodeGroup>

## Metric catalog

<Tabs>
  <Tab title="Usage">
    | Metric              | Description                               |
    | ------------------- | ----------------------------------------- |
    | `genai.requests`    | Number of LLM requests                    |
    | `genai.tokens`      | Total tokens (input + output)             |
    | `genai.cost`        | Total cost in USD                         |
    | `genai.errors`      | Number of failed requests                 |
    | `genai.latency.p50` | Median request latency (ms)               |
    | `genai.latency.p95` | 95th percentile latency (ms)              |
    | `genai.latency.p99` | 99th percentile latency (ms)              |
    | `genai.usage`       | Bundle of request, token, and cost fields |

    <Note>
      Quantile metrics (`genai.latency.p*`) carry a +/-1-2% error band typical of
      t-digest estimation at high cardinality.
    </Note>
  </Tab>

  <Tab title="Evaluator">
    | Metric                      | Description                        |
    | --------------------------- | ---------------------------------- |
    | `genai.evaluator.runs`      | Total **Evaluator** runs           |
    | `genai.evaluator.pass_rate` | Passed / total (ratio in `[0, 1]`) |
    | `genai.evaluator.score.avg` | Average **Evaluator** score        |
  </Tab>

  <Tab title="Guardrail">
    | Metric                       | Description                         |
    | ---------------------------- | ----------------------------------- |
    | `genai.guardrail.runs`       | Total guardrail checks              |
    | `genai.guardrail.block_rate` | Blocked / total (ratio in `[0, 1]`) |
    | `genai.guardrail.triggered`  | Count of blocked checks             |
  </Tab>
</Tabs>

<Info>
  [Evaluator](/docs/evaluators/build) and guardrail metrics read from the same source: every **Evaluator**
  run is recorded as a guardrail check regardless of the **Evaluator**
  implementation type. Pick the metric that matches the question being asked.
</Info>

## Dimensions

The API picks the right index for the query automatically. Asking for an entity dimension (`agent`, `tool`, `tag`, and so on) on a usage metric routes the query through entity attribution; everything else stays on the core usage path.

<Note>
  `billing_billable` is available as a filter field for usage metrics, but not
  as a `group_by` dimension. To break down **Orq.ai**-managed versus customer-owned credentials, use `credential_type` instead. The values `orq_managed` and `customer_byok` are derived at query time from the workspace billing setup, not stored on each event.
</Note>

<Tabs>
  <Tab title="Usage dimensions">
    Pair these with `genai.requests`, `genai.tokens`, `genai.cost`, `genai.errors`, `genai.latency.*`, or `genai.usage`.

    | Dimension          | Notes                                                                           |
    | ------------------ | ------------------------------------------------------------------------------- |
    | `project`          | Workspace project the request is attributed to                                  |
    | `identity`         | End-user identifier from **Identities**                                         |
    | `provider`         | For example, `openai`, `anthropic`                                              |
    | `model`            | For example, `gpt-4o-mini`                                                      |
    | `product`          | Which **Orq.ai** product surface served the request                             |
    | `api_key`          | API key used to authenticate the request                                        |
    | `status_code`      | High-level status (`OK`, `ERROR`)                                               |
    | `http_status_code` | HTTP status from the upstream model                                             |
    | `credential_type`  | `orq_managed` (**Orq.ai**-managed keys) or `customer_byok` (customer BYOK keys) |
  </Tab>

  <Tab title="Entity dimensions">
    Add an entity dimension to any usage metric to break it down by a product entity. The API routes the query to attribution storage automatically.

    | Entity         | Description                         |
    | -------------- | ----------------------------------- |
    | `agent`        | **Agent** that issued the request   |
    | `tool`         | **Tool** invoked during the request |
    | `deployment`   | **Deployment** ID                   |
    | `evaluator`    | **Evaluator** that ran on the trace |
    | `policy`       | **Policy** that matched the request |
    | `tag`          | Tags attached to the request        |
    | `prompt`       | **Prompt** template                 |
    | `dataset`      | **Dataset** used in an experiment   |
    | `conversation` | Conversation grouping               |
    | `thread`       | **Thread** grouping                 |
    | `memory_store` | **Memory Store**                    |
    | `knowledge`    | **Knowledge** base                  |
    | `sheet`        | **Sheet** ID                        |

    <Tip>
      Two conflicting entity dimensions in the same request (for example, `["agent",
              "tool"]`) return `400`. Issue one request per entity dimension.
    </Tip>

    <Tip>
      Advanced attribution queries can group by raw `dimension`, but must include a
      `dimension_type` filter such as `{ "field": "dimension_type", "op": "eq",
              "values": ["agent"] }`. Prefer the entity aliases above for most dashboards.
    </Tip>
  </Tab>

  <Tab title="Evaluator and guardrail dimensions">
    Pair these with `genai.evaluator.*` and `genai.guardrail.*` metrics.

    | Dimension           | Notes                                                               |
    | ------------------- | ------------------------------------------------------------------- |
    | `project`           | Workspace project the request is attributed to                      |
    | `identity`          | End-user identifier from **Identities**                             |
    | `api_key`           | API key used to authenticate the request                            |
    | `policy`            | **Policy** that matched the request                                 |
    | `evaluator`         | **Evaluator** that produced the result                              |
    | `evaluator_name`    | Human-readable **Evaluator** name                                   |
    | `evaluator_type`    | `llm_eval`, `python_eval`, `function_eval`, and so on               |
    | `evaluator_version` | Compare versions over time                                          |
    | `result_type`       | `boolean`, `number`, `categorical`, `string`                        |
    | `result_label`      | Bounded result bucket (`pass`, `fail`, `error`, or category name)   |
    | `evaluation_stage`  | `input` or `output` (aliases: `guardrail_stage`, `evaluator_stage`) |
    | `guardrail_action`  | `block` or other                                                    |
    | `guardrail_origin`  | `rule` or `direct`                                                  |
    | `product`           | Which **Orq.ai** product surface served the request                 |
    | `status_code`       | High-level status (`OK`, `ERROR`)                                   |
  </Tab>
</Tabs>

## Examples by use case

<AccordionGroup>
  <Accordion title="Spend: cost by day (bundle)">
    Get request count, tokens, and cost in one call. Best for headline dashboards.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.usage",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "include_totals": true
      }'
    ```
  </Accordion>

  <Accordion title="Spend: cost by model per hour">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-05-13T00:00:00Z",
        "to":   "2026-05-14T00:00:00Z",
        "grain": "hour",
        "group_by": ["model"]
      }'
    ```
  </Accordion>

  <Accordion title="Spend: BYOK vs Orq.ai-managed credentials">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-04-15T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["credential_type"]
      }'
    ```

    The response carries `dimensions.credential_type` as `"orq_managed"` or `"customer_byok"`.
  </Accordion>

  <Accordion title="Attribution: cost by Agent">
    Grouping by an entity auto-routes the query to attribution storage.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["agent"]
      }'
    ```
  </Accordion>

  <Accordion title="Attribution: tokens by tag, filtered by project">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.tokens",
        "from": "2026-04-15T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["tag"],
        "filters": [
          { "field": "project", "op": "eq", "values": ["proj_123"] }
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Attribution: cost by Tool with model filter">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["tool"],
        "filters": [
          { "field": "model", "op": "in", "values": ["openai/gpt-4o", "openai/gpt-4o-mini"] }
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Latency: p95 by model">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.latency.p95",
        "from": "2026-05-13T00:00:00Z",
        "to":   "2026-05-14T00:00:00Z",
        "grain": "hour",
        "group_by": ["model"]
      }'
    ```

    `metrics["genai.latency.p95"]` is reported in milliseconds.
  </Accordion>

  <Accordion title="Latency: p50, p95, p99 in parallel">
    Quantile metrics are independent calls. Fire them concurrently from the client.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    for metric in genai.latency.p50 genai.latency.p95 genai.latency.p99; do
      curl -X POST "https://api.orq.ai/v2/reporting" \
        -H "Authorization: Bearer $ORQ_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{\"metric\":\"$metric\",\"from\":\"2026-05-13T00:00:00Z\",\"to\":\"2026-05-14T00:00:00Z\",\"grain\":\"hour\"}" &
    done
    wait
    ```
  </Accordion>

  <Accordion title="Errors: count by provider">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.errors",
        "from": "2026-05-13T00:00:00Z",
        "to":   "2026-05-14T00:00:00Z",
        "grain": "hour",
        "group_by": ["provider"]
      }'
    ```
  </Accordion>

  <Accordion title="Errors: error rate by model (client-side ratio)">
    Fetch requests and errors in parallel and divide on the client.

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" -H "Authorization: Bearer $ORQ_API_KEY" -H "Content-Type: application/json" \
      -d '{"metric":"genai.requests","from":"2026-05-13T00:00:00Z","to":"2026-05-14T00:00:00Z","grain":"hour","group_by":["model"]}' &
    curl -X POST "https://api.orq.ai/v2/reporting" -H "Authorization: Bearer $ORQ_API_KEY" -H "Content-Type: application/json" \
      -d '{"metric":"genai.errors","from":"2026-05-13T00:00:00Z","to":"2026-05-14T00:00:00Z","grain":"hour","group_by":["model"]}' &
    wait
    ```
  </Accordion>

  <Accordion title="Evaluator: pass rate by Evaluator and version">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.evaluator.pass_rate",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["evaluator", "evaluator_version"]
      }'
    ```
  </Accordion>

  <Accordion title="Evaluator: average score">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.evaluator.score.avg",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["evaluator"]
      }'
    ```
  </Accordion>

  <Accordion title="Evaluator: runs by result label">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.evaluator.runs",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["evaluator", "result_label"]
      }'
    ```
  </Accordion>

  <Accordion title="Guardrail: block rate by Evaluator and stage">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.guardrail.block_rate",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["evaluator", "evaluation_stage"]
      }'
    ```
  </Accordion>

  <Accordion title="Guardrail: triggers by Policy and stage">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.guardrail.triggered",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["policy", "guardrail_stage"]
      }'
    ```
  </Accordion>

  <Accordion title="Guardrail: filter by origin">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.guardrail.runs",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["evaluator"],
        "filters": [
          { "field": "guardrail_origin", "op": "eq", "values": ["rule"] }
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Multi-tenant: cost per project per day">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["project"]
      }'
    ```
  </Accordion>

  <Accordion title="Multi-tenant: usage per API key">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.usage",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["api_key"],
        "include_totals": true
      }'
    ```
  </Accordion>

  <Accordion title="Identity: cost per end-user Identity">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["identity"]
      }'
    ```
  </Accordion>

  <Accordion title="Identity: requests filtered to a single end-user">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.requests",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "filters": [
          { "field": "identity", "op": "eq", "values": ["user_42"] }
        ]
      }'
    ```
  </Accordion>

  <Accordion title="Time zone: day buckets in America/New_York">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-05-01T04:00:00Z",
        "to":   "2026-05-15T04:00:00Z",
        "grain": "day",
        "time_zone": "America/New_York"
      }'
    ```

    Bucket boundaries align to midnight in the requested zone.
  </Accordion>

  <Accordion title="High resolution: requests per minute, last hour">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.requests",
        "from": "2026-05-14T11:00:00Z",
        "to":   "2026-05-14T12:00:00Z",
        "grain": "minute"
      }'
    ```
  </Accordion>

  <Accordion title="Cross-dimension: cost by credential type and model">
    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    curl -X POST "https://api.orq.ai/v2/reporting" \
      -H "Authorization: Bearer $ORQ_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "metric": "genai.cost",
        "from": "2026-05-01T00:00:00Z",
        "to":   "2026-05-15T00:00:00Z",
        "grain": "day",
        "group_by": ["credential_type", "model"]
      }'
    ```
  </Accordion>
</AccordionGroup>

## Errors

Errors come back as JSON envelopes with a numeric `code`, a human-readable `message`, and an empty `details` array.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": 3,
  "message": "time range exceeds maximum: 11952h0m0s > 90d",
  "details": []
}
```

| HTTP | Code | Reason                                                                                                                                                           |
| ---- | ---- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 400  | 3    | Unknown metric, dimension not allowed, range outside workspace retention, range over 90 days, `from >= to`, grain outside retention, or invalid filter operator. |
| 401  | 16   | Missing or invalid bearer token.                                                                                                                                 |
| 403  | 7    | API key does not have access to the requested project.                                                                                                           |
| 500  | 13   | Unexpected backend failure. Forward `meta.request_id` to support.                                                                                                |

<Tip>
  Every successful response includes `meta.request_id`. Include it in support
  tickets for fast log correlation.
</Tip>

## Limits

| Limit             | Value                                         |
| ----------------- | --------------------------------------------- |
| Query window      | Workspace retention period, capped at 90 days |
| `group_by`        | 5 columns                                     |
| `filters`         | 20 entries                                    |
| `filter.values`   | 100 values per filter                         |
| `limit`           | 5000 bucket rows (default 1000)               |
| Per-query timeout | 30 seconds                                    |