> For the complete documentation index, see [llms.txt](https://docs.digitalapi.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digitalapi.ai/api-gateway/observability/building-custom-reports.md).

# Building custom reports

A **custom report** is a saved analytics view that bundles a chart type, metrics, dimensions, and a time window. Reports run on the same data as Custom Widgets, but each report is a one-click answer to a recurring question. Build a report once for *5xx by API Product, last 7 days* and it is there next sprint without re-applying filters.

### Opening the custom reports page

#### Open custom reports

To open:

1. From the left sidebar, choose **Observability** → **Custom Reports** (`/observability/custom-reports`).

![Figure 10-1. The Custom Reports page.](/files/JaoKhQ2TrC4YI3hwrzIR)

**Verify**

1. The URL is `<your-helix-portal-domain>/observability/custom-reports`.
2. Existing reports are listed; an empty list is normal on day zero.

{% hint style="success" %}
**Result:** Existing reports for the organisation, ready to open.
{% endhint %}

Related tasks:

* [Build a new custom report](#build-a-new-custom-report): author a report.

### Creating a custom report

#### Build a new custom report

**Before you start**

* A sharp question. *5xx rate by environment, last 24h* is sharp; *how is everything* is not.
* The dimensions and metrics. Most useful reports group by service, environment, status, or API Product, and report on request count, error rate, or latency percentiles.

To build a report:

1. With **Custom Reports** open, click **Add report**.
2. Pick a **chart type**: table for leaderboards, line for trends over time, or bar for category comparisons.
3. Pick **dimensions** to group by: service, environment, status, API Product, or route. Multi-dimension reports become matrices.
4. Pick **metrics**: request count, error rate, or p50/p95/p99 latency.
5. Pick the **time window**.
6. Name the report and add a one-line description.
7. Save.

**Verify**

1. The report appears at the top of the list.
2. Opening it renders the chart with the chosen metrics and filters.
3. The report URL is shareable; teammates land on the same view.

{% hint style="success" %}
**Result:** A saved analytics question lives in the portal and reruns on demand.
{% endhint %}

{% hint style="info" %}
**Note:** Reports are organisation-scoped. Anyone with read access to the report sees the same data; reports do not carry per-user state.
{% endhint %}

{% hint style="success" %}
**Tip:** Date-prefix incident-driven reports (for example, `2026-05-07 5xx spike`). Old reports accumulate; a date prefix lets future-you find them.
{% endhint %}

Related tasks:

* [Building custom widgets](/api-gateway/observability/building-custom-widgets.md#building-custom-widgets): per-metric tiles for the slices you watch every day.
* [Investigating with request traces](/api-gateway/observability/investigating-with-request-traces.md#investigating-with-request-traces): drill from a report row into traces.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.digitalapi.ai/api-gateway/observability/building-custom-reports.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.