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

# Create query

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

Creates and saves a query definition for reuse in dashboards and decisions.

### Request body structure

Unlike ad-hoc execute (where `pipeline` is at the top level), saved queries wrap the pipeline inside a `definition` object:

| Field | Required | Description |
| --- | --- | --- |
| `name` | Yes | Query name (max 255 characters) |
| `description` | No | Description (max 1000 characters) |
| `definition` | Yes | Contains `version`, `pipeline`, and optional `meta` — same structure as the ad-hoc execute request body |
| `customerId` | No | OEM customer scope (nullable). Can only be set on create — not updatable. |

### Key IDs from the response

Save the response `id` — you will need it for:

* `PUT /v2/queries/{id}` — update the query
* `POST /v2/queries/{id}/execute` — execute the saved definition
* `GET /v2/queries/{id}/fields` — list output fields for dashboard/decision configuration
* `POST /v2/queries/{id}/predefined-decisions` — create a decision from this query

## Request

Example

```
{
  "createdAt": "2024-01-01T00:00:00.000Z",
  "updatedAt": "2024-01-01T00:00:00.000Z",
  "createdBy": "string",
  "updatedBy": "string",
  "decisions": [
    {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "createdBy": "string",
      "updatedBy": "string",
      "id": "string",
      "name": "string",
      "description": "string",
      "accountId": "string",
      "businessObjectId": "string",
      "sourceType": "BUSINESSOBJECT",
      "sourceId": "string",
      "hitType": "SINGLE",
      "enabled": false,
      "activeFrom": "2024-01-01T00:00:00.000Z",
      "activeUntil": "2024-01-01T00:00:00.000Z",
      "executeOnce": false,
      "executionFrequency": 0,
      "inputFields": [
        {}
      ],
      "outputFields": [
        {}
      ],
      "rules": [
        {}
      ],
      "actions": [
        {}
      ],
      "businessObject": {
        "createdAt": "2024-01-01T00:00:00.000Z",
        "updatedAt": "2024-01-01T00:00:00.000Z",
        "createdBy": "string",
        "updatedBy": "string",
        "id": "string",
        "name": "string",
        "isActive": false,
        "description": "string",
        "fields": [],
        "accountId": "string",
        "subkeys": [],
        "metrics": [],
        "decisions": [],
        "dashboards": [],
        "queries": [],
        "customers": []
      },
      "metric": {
        "id": "string",
        "name": "string",
        "measureId": "string",
        "businessObjectId": "string",
        "evaluationWindow": 0,
        "function": "string",
        "dimensionIds": [],
        "dimensions": [],
        "filters": [],
        "businessObject": {}
      },
      "customer": {
        "id": "string",
        "name": "string"
      }
    }
  ],
  "customer": {
    "id": "string",
    "name": "string"
  },
  "businessObjects": [
    {
      "createdAt": "2024-01-01T00:00:00.000Z",
      "updatedAt": "2024-01-01T00:00:00.000Z",
      "createdBy": "string",
      "updatedBy": "string",
      "id": "string",
      "name": "string",
      "isActive": false,
      "description": "string",
      "fields": [
        {}
      ],
      "accountId": "string",
      "subkeys": [
        "string"
      ],
      "metrics": [
        {}
      ],
      "decisions": [
        {}
      ],
      "dashboards": [
        {}
      ],
      "queries": [],
      "customers": [
        {}
      ]
    }
  ],
  "id": "string",
  "name": "string",
  "description": "string",
  "definition": {
    "version": "2.0",
    "pipeline": {
      "sources": [
        {}
      ],
      "transforms": [
        {}
      ],
      "output": {
        "from": "event_aggregation",
        "select": [],
        "orderBy": [],
        "limit": 100,
        "offset": 0
      }
    },
    "meta": {}
  },
  "template": "string",
  "accountId": "string"
}
```