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

# Building a Query

Build a Luciq Query API request: choose an entity, select metrics, filter and group results, page through rows, compare periods, and query spans.

### The query model

The request body for `/v1/query` and `/v1/query/validate`. Every query names an application (`application` + `environment`) and an `entity`; everything else composes the question.

| Field                    | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| ------------------------ | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `entity` (required)      | string           | What to query. Discover the allowed entities via `/v1/entities`. A `spans` query needs two more conditions. See [Spans](#spans).                                                                                                                                                                                                                                                                                                                                            |
| `application` (required) | string           | Your application's slug, as it appears in the dashboard URL (`https://dashboard.luciq.ai/applications/<slug>/<environment>/…`). Example: `react-native-demo-app`.                                                                                                                                                                                                                                                                                                           |
| `environment` (required) | string           | App environment, for example `production`.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| select                   | SelectItem\[]    | What to compute. Each entry is one of two shapes: a catalog metric `{"metric": "apdex", "as": "..."}`, or a raw aggregate over a column `{"aggregate": "avg", "column": "duration_ms", "as": "..."}`. For the common percentiles, use the catalog metrics (`p50_ms`, `p75_ms`, `p95_ms`); for any other level from 1 to 99, use the `percentile` aggregate with `param` — see [Percentiles](#percentiles). The two shapes never mix in one entry; `as` is optional in both. |
| time\_range              | TimeRange        | Absolute `{gte,lte}` epoch-ms, or relative `{last:"7d"}` (window capped at 3 years).                                                                                                                                                                                                                                                                                                                                                                                        |
| group\_by                | GroupByItem\[]   | Dimensions and time buckets: `{column}` or `{time_bucket}`.                                                                                                                                                                                                                                                                                                                                                                                                                 |
| conditions               | ConditionItem\[] | Filters: `{column, op, value\|values}`. On `app_version`, the value may be a relative marker — `{"latest": true}` or `{"top": N}`.                                                                                                                                                                                                                                                                                                                                          |
| having                   | ConditionItem\[] | Post-aggregation filters, same shape as conditions.                                                                                                                                                                                                                                                                                                                                                                                                                         |
| order\_by                | OrderByItem\[]   | `{column, dir:"asc"\|"desc"}`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| top\_n                   | TopNSpec         | `{by, dir, n}` — n between 1 and 100. Requires `group_by` with a `time_bucket` and exactly one column dimension.                                                                                                                                                                                                                                                                                                                                                            |
| limit                    | integer          | Maximum rows to return — defaults to 100, up to the plan's max (see limits). Results over the cap set `meta.truncated`.                                                                                                                                                                                                                                                                                                                                                     |
| offset                   | integer          | Rows to skip. Needs `order_by`. See [Paging through results](#paging-through-results).                                                                                                                                                                                                                                                                                                                                                                                      |
| compare\_to              | CompareSpec      | A second window to compare against. See [Top N, comparisons and totals](#top-n-comparisons-and-totals).                                                                                                                                                                                                                                                                                                                                                                     |
| include\_totals          | boolean          | Adds a `totals` block. See [Top N, comparisons and totals](#top-n-comparisons-and-totals).                                                                                                                                                                                                                                                                                                                                                                                  |
| time\_zone               | string           | IANA zone for time bucketing.                                                                                                                                                                                                                                                                                                                                                                                                                                               |

#### Example (daily crash-free sessions in the last 7 days)

{% tabs %}
{% tab title="Curl" %}

```bash
curl -s https://api.luciq.ai/v1/query \
  -H "Authorization: Bearer $LUCIQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "application": "my-application",
  "environment": "production",
  "entity": "sessions",
  "select": [
    {
      "metric": "crash_free_sessions",
      "as": "cfs"
    }
  ],
  "group_by": [
    {
      "time_bucket": "day"
    }
  ],
  "time_range": {
    "last": "7d"
  }
}'

```

{% endtab %}

{% tab title="Python" %}

```python
import os, requests

resp = requests.post(
    "https://api.luciq.ai/v1/query",
    headers={"Authorization": f"Bearer {os.environ['LUCIQ_API_KEY']}"},
    json={
        "application": "my-application",
        "environment": "production",
        "entity": "sessions",
        "select": [
            {
                "metric": "crash_free_sessions",
                "as": "cfs"
            }
        ],
        "group_by": [
            {
                "time_bucket": "day"
            }
        ],
        "time_range": {
            "last": "7d"
        }
    },
)
resp.raise_for_status()
data = resp.json()
```

{% endtab %}

{% tab title="Ruby" %}

```ruby
require "net/http"
require "json"

uri = URI("https://api.luciq.ai/v1/query")
req = Net::HTTP::Post.new(uri)
req["Authorization"] = "Bearer #{ENV["LUCIQ_API_KEY"]}"
req["Content-Type"] = "application/json"
req.body = <<~JSON
  {
    "application": "my-application",
    "environment": "production",
    "entity": "sessions",
    "select": [
      {
        "metric": "crash_free_sessions",
        "as": "cfs"
      }
    ],
    "group_by": [
      {
        "time_bucket": "day"
      }
    ],
    "time_range": {
      "last": "7d"
    }
  }
JSON

res = Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(req) }
data = JSON.parse(res.body)

```

{% endtab %}

{% tab title="Node.js" %}

```javascript
const resp = await fetch("https://api.luciq.ai/v1/query", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.LUCIQ_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "application": "my-application",
    "environment": "production",
    "entity": "sessions",
    "select": [
      {
        "metric": "crash_free_sessions",
        "as": "cfs"
      }
    ],
    "group_by": [
      {
        "time_bucket": "day"
      }
    ],
    "time_range": {
      "last": "7d"
    }
  }),
});
const data = await resp.json();
```

{% endtab %}
{% endtabs %}

Response is columnar, column names plus row arrays with a `meta` block carrying `query_id` and `elapsed_ms`. It also carries `truncated` and `next_offset` when more rows exist, and `resolved` when relative version markers were used.

```json
{
  "columns": ["bucket_ms", "cfs"],
  "rows": [[1791590400000, 0.993], [1791676800000, 0.991]],
  "meta": { "query_id": "66310034-…", "elapsed_ms": 11 }
}
```

A time bucket's column is `bucket_ms` (bucket start, epoch milliseconds) unless you name it with `as`.

### Percentiles <a href="#percentiles" id="percentiles"></a>

The APM entities have catalog metrics for the common percentiles: `p50_ms`, `p75_ms` and `p95_ms`. For any other level, such as p90 or p99, use the `percentile` aggregate and pass the level in `param`:

```json
{ "aggregate": "percentile", "column": "loading_time_ms", "param": 99 }
```

* `param`: **integer** (required with `percentile`) — The level, from 1 to 99. `99` is the 99th percentile.
* The output column is `p{level}_{column}`, for example `p99_loading_time_ms`. Set `as` to name it yourself.
* Only some columns take a percentile. In `/v1/entities`, these columns list `percentile` in their `aggregates`: `response_time_ms` (networks), `duration_ms` (launches, flows and spans), `loading_time_ms` (screen\_loading), the launch and screen loading stage columns, and the screen loading web vitals.
* One query can ask for up to 6 distinct column and level pairs.

A level outside 1 to 99, a seventh pair, or a column that doesn't take a percentile returns `400 invalid_request`. For a column that doesn't take one, `details.valid_aggregates` lists the aggregates it does take.

#### Example (p90 and p99 screen loading per screen in the last 30 days)

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "screen_loading",
  "select": [
    { "aggregate": "percentile", "column": "loading_time_ms", "param": 90 },
    { "aggregate": "percentile", "column": "loading_time_ms", "param": 99 },
    { "metric": "count" }
  ],
  "group_by": [{ "column": "screen_label" }, { "column": "screen_uuid" }],
  "order_by": [{ "column": "p99_loading_time_ms", "dir": "desc" }],
  "time_range": { "last": "30d" },
  "limit": 20
}
```

```json
{
  "columns": ["screen_label", "screen_uuid", "p90_loading_time_ms", "p99_loading_time_ms", "count"],
  "rows": [["CheckoutViewController", "3edbcb3a-…", 1840.2, 4215.7, 12873], ["HomeViewController", "1158a814-…", 910.4, 2380.1, 48210], …],
  "meta": { "query_id": "8c1f2a07-…", "elapsed_ms": 42 }
}
```

Grouping by `screen_uuid` as well keeps screens that share a name apart, so each row is one screen.

### Paging through results <a href="#paging-through-results" id="paging-through-results"></a>

Results return 100 rows by default. Set `limit` up to your plan's maximum (see `limits` in `GET /v1/entities`).

To page, add `order_by` and `offset`. When more rows exist, the response's `meta.next_offset` is the `offset` for the next page.

`offset + limit` can't exceed 50,000 for aggregated results, or 10,000 when listing individual records.

**Example:** the second page of crash groups in the last 30 days, ordered by count.

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "crashes",
  "select": [{ "metric": "count", "as": "count" }],
  "group_by": [{ "column": "crash_number" }],
  "order_by": [{ "column": "count", "dir": "desc" }],
  "time_range": { "last": "30d" },
  "limit": 100,
  "offset": 100
}
```

### Top N, comparisons and totals <a href="#top-n-comparisons-and-totals" id="top-n-comparisons-and-totals"></a>

**Top N.** `top_n` keeps the top N groups. `by` must be a selected alias. `dir` defaults to `desc`. `n` is at most 100. Top N returns up to `n` rows per time bucket, so set `limit` to at least `n` × buckets.

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "networks",
  "select": [
    { "metric": "count", "as": "count" },
    { "metric": "failure_rate", "as": "failure_rate" }
  ],
  "group_by": [{ "time_bucket": "hour" }, { "column": "endpoint_label" }],
  "top_n": { "n": 5, "by": "count", "dir": "desc" },
  "time_range": { "last": "24h" },
  "limit": 500
}
```

{% hint style="warning" %}
The older group columns `endpoint`, `launch_group`, `screen_group` and `flow_group` still work, but they are deprecated and will be removed. Use the label and uuid columns below instead.
{% endhint %}

Each APM group has two columns: a label and a uuid. Each column returns one value. Group by one or both, and filter by either with `eq`, `neq`, `in` or `not_in`.

| Entity                               | Label                                                                                     | UUID            |
| ------------------------------------ | ----------------------------------------------------------------------------------------- | --------------- |
| `networks`                           | `endpoint_label`: the method and URL pattern, for example `POST api.example.com/client/*` | `endpoint_uuid` |
| `launches`                           | `launch_type`: `cold`, `warm` or `hot`                                                    | `launch_uuid`   |
| `screen_loading`, `screen_rendering` | `screen_label`: the screen name                                                           | `screen_uuid`   |
| `flows`                              | `flow_label`: the flow name                                                               | `flow_uuid`     |

Two screens can have the same name. A `screen_label` filter matches all of them. To tell them apart, also group by `screen_uuid`.

A `spans` query names its parent group by one of these uuids. See [Spans](#spans).

You can't sort by a group column: `order_by` on a label or uuid column returns a 400. Sort by a metric instead, for example `count`.

Grouping by `launch_type` returns the type once. It no longer adds a `launch_type_label` column.

**Trace attributes.** On `networks` and `flows`, use `trace_attributes.<key>` to read a trace attribute by its key, for example `trace_attributes.songId`. It works in `select`, `group_by`, `conditions` and `order_by`. Each flow and each endpoint stores its own attribute keys, so the query must name one flow (`flow_label` or `flow_uuid` with `eq`) or one endpoint (`endpoint_label` or `endpoint_uuid` with `eq`).

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "flows",
  "select": [{ "metric": "count" }],
  "conditions": [
    { "column": "flow_label", "op": "eq", "value": "song_play" },
    { "column": "trace_attributes.status", "op": "eq", "value": "skipped" }
  ],
  "group_by": [{ "column": "trace_attributes.songId" }],
  "time_range": { "last": "7d" }
}
```

The response names the column `trace_attributes.songId`. The same query works in production and development, even when the attribute has a different position in each. If the flow has no attribute with that key, the error lists the keys it has.

**Comparisons.** `compare_to` takes `{"period": "previous_period"}` or an absolute window `{"gte": …, "lte": …}`. It adds a `<alias>_previous` column for each metric. It doesn't work with `week` or `month` buckets.

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "sessions",
  "select": [{ "metric": "crash_free_sessions", "as": "cfs" }],
  "group_by": [{ "time_bucket": "day" }],
  "time_range": { "last": "7d" },
  "compare_to": { "period": "previous_period" }
}
```

The response columns are `bucket_ms`, `cfs`, and `cfs_previous`.

**Totals.** `include_totals` adds a `totals` block with each metric over the whole window.

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "sessions",
  "select": [{ "metric": "count", "as": "sessions" }],
  "group_by": [{ "time_bucket": "day" }],
  "time_range": { "last": "7d" },
  "include_totals": true
}
```

```json
{
  "columns": ["bucket_ms", "sessions"],
  "rows": [[1791590400000, 1250], [1791676800000, 1310], …],
  "totals": { "columns": ["sessions"], "rows": [[8870]] },
  "meta": { "query_id": "66310034-…", "elapsed_ms": 14 }
}
```

`compare_to` and `include_totals` can't be combined with `top_n`.

#### Reference

**Aggregates:** `count`, `sum`, `avg`, `min`, `max`, `uniq`, `percentile` (with `param`, the level from 1 to 99; see [Percentiles](#percentiles))

**Column types:** `string`, `int`, `float`, `bool`, `timestamp`, `array`

**Operators:** `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `not_in`, `like`, `ilike`. For array columns: `has`, `has_any`, `has_all`, `not_has`

**Time buckets** (`group_by[].time_bucket`): `minute`, `hour`, `day`, `week`, `month`. `minute` works only over short windows; a window too long for the bucket returns 400 with the limit.

**Relative ranges** (`time_range.last`): a number plus a unit — `m` (minutes), `h` (hours), `d` (days), `w` (weeks). Example: `{"last": "30d"}`. Maximum 3 years.

### Spans <a href="#spans" id="spans"></a>

A span is a child operation inside one network call, app launch, flow, screen load or screen render. Examples are a network stage, a database query and a custom span.

Use the `spans` entity to find the spans that slow down a parent. It also shows how often each span runs. Its metrics match the spans table on the dashboard.

One query covers the spans of one parent group, for example one flow or one endpoint.

#### Required conditions

Every `spans` query needs these two conditions. Together they name the parent group.

* `parent`: **string** (required) — The kind of parent. One of `networks`, `launches`, `flows`, `screen_loading` or `screen_rendering`. Use `eq`, or `in` with one value.
* `parent_uuid`: **string** (required) — The uuid of one parent group. Use `eq`, or `in` with one value.

Your API key must cover the parent entity. For example, `parent` `flows` needs a key that covers `flows`. See [Authentication](https://docs.luciq.ai/references/api-access/authentication.md#data-types-and-entities).

To get the uuid, query the parent entity and group by its uuid column:

| `parent`                             | Group the parent entity by |
| ------------------------------------ | -------------------------- |
| `networks`                           | `endpoint_uuid`            |
| `launches`                           | `launch_uuid`              |
| `flows`                              | `flow_uuid`                |
| `screen_loading`, `screen_rendering` | `screen_uuid`              |

For `flows`, the uuid must belong to a flow, not to a custom trace.

For example, this query lists your busiest flows with their uuids:

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "flows",
  "select": [{ "metric": "count" }],
  "group_by": [{ "column": "flow_label" }, { "column": "flow_uuid" }],
  "order_by": [{ "column": "count", "dir": "desc" }],
  "time_range": { "last": "7d" },
  "limit": 10
}
```

```json
{
  "columns": ["flow_label", "flow_uuid", "count"],
  "rows": [["checkout", "7f3c9a2e-5b1d-4e8a-9c3f-2d6b8a1e4f70", 48210], ["song_play", "b61d04f8-3a7c-4d2e-8f15-9c0e6a4b7d31", 31544], …],
  "meta": { "query_id": "2b7e51c4-…", "elapsed_ms": 18 }
}
```

#### Columns

* `span_name`: **string** — The span's name. A network span's name is the method and the URL pattern, as the SDK reports them, for example `post api.example.com/v2/cart`. Group by it, or filter it with `eq`, `neq`, `in` or `not_in`.
* `span_type`: **string** — The kind of span. Group by it together with `span_name`. You can't filter on it. The values are `network`, `screen_loading`, `extended_stage`, `cold_app_launch`, `fragment_loading`, `database_query`, `app_resume`, `network_stage`, `jetpack_compose`, `webviews_loading`, `sub_screen_loading` and `custom_span`.
* `duration_ms`: **float** — The span's duration in milliseconds. It takes the `percentile` aggregate. See [Percentiles](#percentiles).
* `start_time`: **timestamp** — When the span started. You can only select it, and only when you list rows.
* The parent's dimensions. They have the same names as on the parent entity.

All parents have `app_version`, `platform`, `os_version`, `device`, `experiments` and `experiment`. Filter on `experiments` with `has`, `not_has`, `has_any` or `has_all`. `experiment` is for `group_by` only, with one row per experiment; a condition on it returns 400. Some parents have more columns:

| `parent`           | More columns                    |
| ------------------ | ------------------------------- |
| `networks`         | `country`, `carrier`, `radio`   |
| `launches`         | `first_screen`                  |
| `screen_rendering` | `power_saving`, `battery_level` |

`GET /v1/entities` lists all of these columns under `spans`. Each column's description names the parents that have it.

On `launches` and `flows`, an `experiments` filter leaves out spans whose `span_type` is `network`. The dashboard does the same.

#### Metrics

Each metric works on some parents only.

| Metric                        | Parents                 | Definition                                                                                                                                                            |
| ----------------------------- | ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `count`                       | All                     | The number of span occurrences.                                                                                                                                       |
| `p50_ms`, `p75_ms`, `p95_ms`  | All                     | The 50th, 75th or 95th percentile of `duration_ms`.                                                                                                                   |
| `percentile` on `duration_ms` | All                     | Any percentile level from 1 to 99, set in `param`.                                                                                                                    |
| `frequency_rate`              | All                     | The share of parent occurrences that contain the span, from 0 to 1.                                                                                                   |
| `average_calls`               | All except `networks`   | The number of spans for each parent occurrence that contains the span. A stage that runs 3 times in one screen load reads 3. The dashboard shows 1.0 for stage spans. |
| `frozen_frames_overlap_rate`  | `screen_rendering` only | The share of span occurrences that overlap a frozen frame, from 0 to 1.                                                                                               |
| `slow_frames_overlap_rate`    | `screen_rendering` only | The share of span occurrences that overlap a slow frame, from 0 to 1.                                                                                                 |

* Percentiles count only successful spans with a duration above zero.
* `frequency_rate` divides by all parent occurrences. It uses the same time range and the same filters as the query.
* The dashboard shows the overlap rates as percentages. The API returns them from 0 to 1.

#### Example (the slowest spans of one flow in the last 7 days)

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "spans",
  "conditions": [
    { "column": "parent", "op": "eq", "value": "flows" },
    { "column": "parent_uuid", "op": "eq", "value": "7f3c9a2e-5b1d-4e8a-9c3f-2d6b8a1e4f70" }
  ],
  "select": [
    { "metric": "count" },
    { "metric": "p95_ms" },
    { "aggregate": "percentile", "column": "duration_ms", "param": 99 },
    { "metric": "frequency_rate" },
    { "metric": "average_calls" }
  ],
  "group_by": [{ "column": "span_name" }, { "column": "span_type" }],
  "order_by": [{ "column": "p95_ms", "dir": "desc" }],
  "time_range": { "last": "7d" },
  "limit": 50
}
```

```json
{
  "columns": ["span_name", "span_type", "count", "p95_ms", "p99_duration_ms", "frequency_rate", "average_calls"],
  "rows": [
    ["load_cart_items", "custom_span", 61892, 2410.5, 5120.8, 0.98, 1.31],
    ["post api.example.com/v2/cart", "network", 52207, 1385.2, 3904.6, 0.91, 1.19],
    ["SELECT cart_items", "database_query", 9449, 212.7, 640.3, 0.14, 1.4],
    …
  ],
  "meta": { "query_id": "c90d3f12-…", "elapsed_ms": 37 }
}
```

`load_cart_items` ran in 98% of the flow's occurrences. In each of those occurrences, it ran 1.31 times on average.

#### Example (frozen and slow frame overlap per span on one screen)

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "spans",
  "conditions": [
    { "column": "parent", "op": "eq", "value": "screen_rendering" },
    { "column": "parent_uuid", "op": "eq", "value": "e2a59b07-6c4f-4a18-b3d9-8f71c0e5a6b2" }
  ],
  "select": [
    { "metric": "count" },
    { "metric": "frozen_frames_overlap_rate" },
    { "metric": "slow_frames_overlap_rate" }
  ],
  "group_by": [{ "column": "span_name" }, { "column": "span_type" }],
  "order_by": [{ "column": "frozen_frames_overlap_rate", "dir": "desc" }],
  "time_range": { "last": "30d" },
  "limit": 20
}
```

```json
{
  "columns": ["span_name", "span_type", "count", "frozen_frames_overlap_rate", "slow_frames_overlap_rate"],
  "rows": [
    ["decode_product_images", "custom_span", 18230, 0.112, 0.384],
    ["get api.example.com/v2/recommendations", "network", 40512, 0.031, 0.157],
    …
  ],
  "meta": { "query_id": "5a8e0b6d-…", "elapsed_ms": 29 }
}
```

11.2% of the `decode_product_images` occurrences overlapped a frozen frame. The dashboard shows this value as 11.2%.

#### Example (the slowest span occurrences of one endpoint)

A `select` of plain columns, such as `{ "column": "duration_ms" }`, lists span occurrences. Each row is one span occurrence. A row can carry `span_name`, `span_type`, `duration_ms`, `start_time` and the parent's dimensions. Rows carry no user identifiers. Without `order_by`, the newest rows come first.

```json
{
  "application": "my-application",
  "environment": "production",
  "entity": "spans",
  "conditions": [
    { "column": "parent", "op": "eq", "value": "networks" },
    { "column": "parent_uuid", "op": "eq", "value": "c4a81f6d-2e3b-4f90-a7d5-6b9e0c1f8a24" }
  ],
  "select": [
    { "column": "start_time" },
    { "column": "span_name" },
    { "column": "span_type" },
    { "column": "duration_ms" },
    { "column": "app_version" },
    { "column": "os_version" }
  ],
  "order_by": [{ "column": "duration_ms", "dir": "desc" }],
  "time_range": { "last": "24h" },
  "limit": 20
}
```

```json
{
  "columns": ["start_time", "span_name", "span_type", "duration_ms", "app_version", "os_version"],
  "rows": [
    ["2026-11-15T09:42:17.318Z", "server_processing", "network_stage", 8421.6, "4.12.0", "17.5"],
    ["2026-11-15T14:03:51.904Z", "downloading_response", "network_stage", 6109.3, "4.12.0", "18.1"],
    ["2026-11-14T21:27:08.112Z", "server_processing", "network_stage", 5877.0, "4.11.2", "17.5"],
    …
  ],
  "meta": { "query_id": "e47c2a90-…", "elapsed_ms": 52 }
}
```

#### Limits and errors

These requests return `400 invalid_request`:

* A query without `parent` or without `parent_uuid`.
* A `parent` with another operator or another value. The error lists the five parents.
* A `parent_uuid` that names more than one group. Query one group at a time.
* A `group_by` on `span_type` without `span_name`.
* A condition on `span_type`.
* A metric or column that the parent doesn't have, for example `average_calls` on `networks`. `details.available_on` lists the parents that have it.

An unknown `parent_uuid` returns `404 not_found`. An unknown group uuid on the parent entity does the same.

`frequency_rate` and `average_calls` have more limits. A query with either metric returns `400 invalid_request` when it:

* Sorts by the metric. Sort by `count` or a percentile instead.
* Filters on the metric with `having`.
* Uses `top_n`, `compare_to` or `include_totals`. Ask for the metric in a separate query.
* Doesn't group by `span_name`.
* Groups by `experiment`. Filter on `experiments` with `has_any` instead.
* Has a condition on `duration_ms`.
* Asks for a breakdown that is too wide. Group by fewer columns, use fewer time buckets, or shorten the time range.


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.luciq.ai/references/api-access/building-a-query.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
