---
source_url: https://www.pubnub.com/docs/admin-api/v2026-05-26/execute-query
title: Execute query
---

# Execute query

> For AI agents: documentation index at https://www.pubnub.com/llms-full.txt

Executes a query definition without saving it. Use this to preview results before creating a saved query, dashboard, or decision.

### Pipeline structure

The query `pipeline` follows a three-stage model:

1. **Sources** — Define where data comes from (`businessObject` or `reference`). Each source specifies fields, time ranges, and filters.
2. **Transforms** — Optional processing steps: `aggregate`, `window`, `join`, `dedupe`, `calculate`, `unnest`, `filter_join`. Each transform references an `input` (a source `id` or previous transform `id`).
3. **Output** — Specifies which stage to return results from (`from`), which fields to `select`, sorting (`orderBy`), and pagination (`limit`/`offset`).

### Conditional requirements

| Field | Condition |
| --- | --- |
| `source.businessObjectId` | Required when `source.type` is `businessObject` |
| `source.referenceId` | Required when `source.type` is `reference` |
| `timeRange.relative` / `timeRange.absolute` | Mutually exclusive — specify only one |

## Request

Example

```
{
  "data": [
    {}
  ],
  "executionTime": 37,
  "queryDefinition": {
    "version": "2.0",
    "pipeline": {
      "sources": [
        {}
      ],
      "transforms": [
        {}
      ],
      "output": {
        "from": "event_aggregation",
        "select": [],
        "orderBy": [],
        "limit": 100,
        "offset": 0
      }
    },
    "meta": {}
  }
}
```