---
title: "Run one query. Counts toward the monthly quota, which is soft: it never rejects."
method: POST
path: "/v1/query"
---

# Run one query. Counts toward the monthly quota, which is soft: it never rejects.

`POST /v1/query`

## Request

- Base URL: `https://api.instabug.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.instabug.com/v1/query`
- Auth: HTTP bearer

## Request body

- QueryRequest
  - `application` string
  - `application_token` string
  - `compare_to` CompareSpec
    - `gte` integer
    - `lte` integer
    - `period` string
  - `conditions` ConditionItem[]
    - `column` string, required
    - `op` 'eq' | 'gt' | 'gte' | 'has' | 'has_all' | 'has_any' | 'ilike' | 'in' | 'like' | 'lt' | 'lte' | 'neq' | 'not_has' | 'not_ilike' | 'not_in' | 'not_like'
    - `value` unknown
    - `values` unknown
  - `entity` string, required
  - `environment` string
  - `group_by` GroupByItem[]
    - `as` string
    - `column` string
    - `time_bucket` string
  - `having` ConditionItem[]
    - `column` string, required
    - `op` 'eq' | 'gt' | 'gte' | 'has' | 'has_all' | 'has_any' | 'ilike' | 'in' | 'like' | 'lt' | 'lte' | 'neq' | 'not_has' | 'not_ilike' | 'not_in' | 'not_like'
    - `value` unknown
    - `values` unknown
  - `include_totals` boolean
  - `limit` integer: Row limit. Omitted or 0 defaults to 100, then the plan's sync max_rows clamps it (see /v1/entities limits).
  - `offset` integer
  - `order_by` OrderByItem[]
    - `column` string, required
    - `dir` 'asc' | 'desc'
  - `referrer` string
  - `select` SelectItem[], required
    - `aggregate` 'avg' | 'count' | 'max' | 'min' | 'percentile' | 'sum' | 'uniq'
    - `as` string
    - `column` string
    - `metric` string
    - `param` union: Aggregate parameter, a string or a number. For percentile it is the level, an integer from 1 to 99. Required with that aggregate, refused elsewhere. Columns list percentile in /v1/entities column_info aggregates when they support it. At most 6 distinct (column, level) pairs per query. Default alias: p{N}_{column} (p99_response_time_ms).
      - string
      - number
  - `time_range` TimeRange, required
    - `gte` integer
    - `last` string
    - `lte` integer
  - `time_zone` string
  - `top_n` TopNSpec
    - `by` string, required
    - `dir` string
    - `n` integer, required

## Response `200`

Columnar result

- QueryResponse
  - `columns` string[], required
  - `meta` Meta, required
    - `elapsed_ms` integer, required
    - `next_offset` integer
    - `query_id` string, required
    - `resolved` object
    - `store` string
    - `total` integer
    - `truncated` boolean
  - `rows` array[], required
    - unknown[]
      - unknown
  - `totals` Totals
    - `columns` string[], required
    - `rows` array[], required
      - unknown[]
        - unknown

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key
- `403`: Key does not cover the application, entity scope, or level
- `404`: Unknown entity
- `422`: Valid query, but it exceeded a resource budget (code budget_exceeded; details.cap + details.limit)
- `429`: Rate limited or too many concurrent queries. details.reason says which (rate_limit | concurrency); Retry-After says when to retry. The monthly quota never rejects

---

[API](https://skmtc.dev/instabug/apis/luciq-query-api.md) - [All operations](https://skmtc.dev/instabug/apis/luciq-query-api/llms.txt) - [OpenAPI document](https://skmtc.dev/instabug/apis/luciq-query-api/revisions/e446f3c9b6b4?raw)