Execution

Run a Query to refresh its embedded Dataset, execute it for raw results, preview a sample of rows, or benchmark how long it takes.

Execution routes operate on a single Query resolved from the URL. _run and _benchmark require the query:run permission and reject embedded Queries with 400 (run those through their parent Dataset's refresh instead). _execute requires query:run and applies no embedded restriction. sample and exporters only compile or inspect the Query, so they perform no query:run check.

Endpoint Overview

Endpoint	Purpose	Returns
`POST /_run`	Create or refresh the caller's embedded Dataset	The populated Dataset (HAL)
`POST /_execute`	Compile and run the Query, rendered to a format	The rendered result body
`GET /sample`	Preview rows without running or persisting	An `eu.collection` envelope
`POST /_benchmark`	Time a full execution	A benchmark result object
`GET /dataset`	Read the caller's embedded Dataset	The Dataset (HAL), or `404`
`GET /exporters`	List eligible export formats	A HAL collection of exporters

POST /api/queries/{id}/_run

Create or refresh the caller's embedded Dataset for the Query and return the populated Dataset.

Authentication: Required

Permission: query:run

Path Parameters:

Parameter	Type	Description
`id`	string	Query id (UUID) or natural id

Request Body:

Field	Type	Required	Description
`params`	object	No	Input parameter values matching the Query's inputs
`progress`	string	No	Task monitor id for progress updates

params and progress are the only payload fields. The supplied params are persisted to the caller's user settings, so the next run defaults to them.

Example Request:

{
  "params": {
    "startDate": "2024-01-01",
    "region": "West"
  }
}

Response:

Responds 200 with the populated embedded Dataset as HAL (the same shape as GET /api/datasets/{id}), not a flat status object. The run executes inside a task: it finds or creates the embedded Dataset, sets its params and TTL, persists the params to user settings, refreshes the data, and returns the Dataset. The TTL defaults to the tenant's queryDatasetTTL (60 minutes).

Run a query (create/refresh embedded dataset)POST /api/queries/admin:top-orders-by-country/_run

POST /api/queries/{id}/_run creates or refreshes the caller’s embedded Dataset for the query and returns the populated Dataset (HAL), status 200 — not a flat status object. The TTL defaults to the tenant queryDatasetTTL (60 min). Payload is { params?, progress? }; `params` are persisted to the caller’s user settings. Rejects an embedded query with 400 (run it via the parent Dataset instead).

Request body

{}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run"
    },
    "inf:draft": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/draft"
    },
    "inf:run": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_run"
    },
    "inf:benchmark": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_benchmark"
    },
    "inf:refresh": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_refresh"
    },
    "inf:data": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/data{?start,limit,q,sort,show,report}",
      "templated": true
    },
    "inf:user-settings": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/settings"
    },
    "inf:query": {
      "href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002"
    },
    "inf:owner": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/owner"
    },
    "inf:search": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_search{?query,_source,sort,from,size,searchType,aggs,report,aggregations,alias,snapshots}",
      "templated": true
    },
    "inf:mapping": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/mapping"
    },
    "inf:job-templates": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/job-templates"
    },
    "inf:fields": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/fields"
    },
    "inf:count": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/count"
    },
    "inf:comments": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/comments"
    },
    "inf:visuals": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/visuals"
    },
    "inf:visual-templates": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/visual-templates"
    },
    "inf:dataset-tags": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/tags"
    },
    "inf:dataset-tag": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/tags/{tagId}",
      "templated": true
    },
    "inf:discover": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/discover"
    },
    "inf:filters": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/filters"
    },
    "inf:dataset-shares": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/shares"
    },
    "inf:flow": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/flow"
    },
    "inf:group": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/group"
    },
    "inf:group-rows": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/group-rows"
    },
    "inf:dataset-share": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/shares/{principalId}",
      "templated": true
    },
    "inf:import": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/_import"
    },
    "inf:exceptions": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/_exceptions"
    },
    "inf:search-aggregates": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/_search-aggregates"
    },
    "inf:exporters": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/exporters"
    },
    "inf:favorite": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/favorite"
    },
    "inf:export-bundle": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_run/_export"
    },
    "edit": {
      "href": "https://informer.example.com/api/reports/00000000-0000-4000-8000-000000000001/_edit"
    }
  },
  "naturalId": "00000000-0000-4000-8000-000000000001",
  "permissions": {
    "edit": true,
    "share": true,
    "delete": true,
    "write": true,
    "addVisual": true,
    "deleteVisual": true,
    "changeOwner": true,
    "copy": true,
    "rename": true,
    "refresh": true,
    "modifyFlows": true,
    "replaceFile": true,
    "modifySettings": true,
    "createDataView": true,
    "assignTags": true,
    "createFilter": true,
    "scriptFields": true,
    "setIndex": false
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "tenant": "acme",
  "ownerId": "admin",
  "slug": null,
  "name": null,
  "description": null,
  "embedded": true,
  "esIndex": "docsex.acme.00000000-0000-4000-8000-000000000001.1700000000000",
  "esIndexName": "00000000-0000-4000-8000-000000000001",
  "esType": "data",
  "records": 5,
  "size": "524288",
  "source": null,
  "sourceId": null,
  "params": {},
  "dataUpdatedAt": "2026-01-15T16:20:00.000Z",
  "dataExpiresAt": "2026-01-15T16:20:00.000Z",
  "ttl": 3600000,
  "append": false,
  "shared": false,
  "timestampField": null,
  "lastDurationMillis": "1500",
  "windowSize": 500,
  "settings": {},
  "flow": [],
  "esId": null,
  "lastQueriedAt": "2026-01-15T16:20:00.000Z",
  "esWorkers": 1,
  "datasetFieldReportAccess": false,
  "parentId": null,
  "templateProcessorId": null,
  "deleteDate": null,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "datasourceId": null,
  "reportId": null,
  "queryId": "00000000-0000-4000-8000-000000000002",
  "editingId": null,
  "folderId": null
}

Captured from the API examples test suite; ids and timestamps are normalized.

Embedded Query restriction

This endpoint returns 400 Bad Request for an embedded Query. Embedded Queries must be refreshed through their parent Dataset.

Progress tracking

Pass a progress id to receive task-monitor updates as the Query executes.

POST /api/queries/{id}/_execute

Compile and run the Query, returning the rendered result directly.

Authentication: Required

Permission: query:run

Path Parameters:

Parameter	Type	Description
`id`	string	Query id (UUID) or natural id

Query Parameters:

Parameter	Type	Default	Description
`output`	string	the Query's own format	Output format (for example `json`, `csv`, `excel`, `pdf`)
`limit`	integer	`-1`	Row limit (`-1` for unlimited)
`pretty`	boolean	`false`	Pretty-print JSON output
`timezone`	string	-	Timezone for date formatting
`applyFormatting`	boolean	`true`	Apply field formatting to results

Request Body:

The body is the raw input-params object as flat key/value pairs. It is not wrapped in a params key.

{
  "startDate": "2024-01-01",
  "region": "West"
}

Response:

Responds 200 with the rendered result directly, with no HAL envelope and no _embedded["inf:record"] wrapping. With the default JSON output the body is a JSON string encoding an array of row objects.

Execute a queryPOST /api/queries/admin:top-orders-by-country/_execute?output=json&applyFormatting=false

POST /api/queries/{id}/_execute compiles and runs the query, returning the rendered result directly (no HAL envelope). With the default JSON output the body is a JSON string encoding an array of row objects. The request body is the raw input-params object (flat key/value), NOT wrapped in `params`. Query params: output (default = query format), limit (default -1 = unlimited), pretty, timezone, applyFormatting (default true). Requires query:run.

Request body

{}

Response · 200

"[{\"OrderID\":10248,\"CustomerID\":\"VINET\",\"ShipCountry\":\"France\",\"ShipCity\":\"Reims\"},{\"OrderID\":10249,\"CustomerID\":\"TOMSP\",\"ShipCountry\":\"Germany\",\"ShipCity\":\"Münster\"},{\"OrderID\":10250,\"CustomerID\":\"HANAR\",\"ShipCountry\":\"Brazil\",\"ShipCity\":\"Rio de Janeiro\"},{\"OrderID\":10251,\"CustomerID\":\"VICTE\",\"ShipCountry\":\"France\",\"ShipCity\":\"Lyon\"},{\"OrderID\":10252,\"CustomerID\":\"SUPRD\",\"ShipCountry\":\"Belgium\",\"ShipCity\":\"Charleroi\"}]"

Captured from the API examples test suite; ids and timestamps are normalized.

Other output formats

Setting output to csv, excel, or pdf produces a file or stream body rather than JSON, so those responses are not captured here. Use GET /api/queries/{id}/exporters to discover the formats eligible for a Query.

Execute versus run

Use _execute for raw data in API integrations and one-off exports. Use _run when results should persist as a Dataset for filtering, sorting, and visualization.

GET /api/queries/{id}/sample

Preview the Query's rows without running it or creating a Dataset.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Query id (UUID)

Query Parameters:

Parameter	Type	Default	Description
`size`	integer	`50`	Number of sample rows to return

The sample route compiles the Query directly from {id} cast to a UUID, so it requires the Query's UUID rather than its natural id.

Response:

Responds 200 with an eu.collection envelope ({ start, count, total, items }, plus a HAL _links.self) holding up to size rows. The route only compiles the Query, so it runs no query:run check and applies no embedded restriction, making it the lightweight preview path during Query design.

Sample a queryGET /api/queries/00000000-0000-4000-8000-000000000001/sample?size=5

GET /api/queries/{id}/sample compiles the query and returns up to `size` rows (default 50) as an eu.collection envelope ({ start, count, total, items }). It only compiles (no query:run permission check, no embedded restriction), making it the lightweight preview path during query design.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000001/sample?size=5"
    }
  },
  "items": [
    {
      "OrderID": 10248,
      "CustomerID": "VINET",
      "ShipCountry": "France",
      "ShipCity": "Reims"
    },
    {
      "OrderID": 10249,
      "CustomerID": "TOMSP",
      "ShipCountry": "Germany",
      "ShipCity": "Münster"
    },
    {
      "OrderID": 10250,
      "CustomerID": "HANAR",
      "ShipCountry": "Brazil",
      "ShipCity": "Rio de Janeiro"
    },
    "… 2 more items (5 total) — omitted from docs"
  ],
  "start": 0,
  "count": 5,
  "total": 5
}

Captured from the API examples test suite; ids and timestamps are normalized.

Limited results

A sample is capped at the requested size. It does not represent the full result set and may omit distinct values.

POST /api/queries/{id}/_benchmark

Time a full execution of the Query.

Authentication: Required

Permission: query:run

Path Parameters:

Parameter	Type	Description
`id`	string	Query id (UUID) or natural id

Request Body:

Field	Type	Required	Description
`params`	object	No	Input parameter values
`config`	object	No	Benchmark configuration (for example `limit` to cap rows, or `index` to write into a scratch index)
`progress`	string	No	Task monitor id

Example Request:

{
  "config": {
    "limit": 5
  }
}

Response:

Responds 200 with the benchmark result of a full execution: { records, time, containsErrors, errorMessage }. It does not return a { runs, stats } shape. time is the elapsed execution time and records is the number of rows produced. The benchmark runs inside a task.

Benchmark a queryPOST /api/queries/admin:top-orders-by-country/_benchmark

POST /api/queries/{id}/_benchmark times a full query execution and returns { records, time, containsErrors, errorMessage } — NOT the { runs, stats } shape the docs show. Payload is { params?, config?, progress? }; config can cap rows (limit) or write into a scratch index (index). Rejects an embedded query with 400.

Request body

{
  "config": {
    "limit": 5
  }
}

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/queries/admin%3Atop-orders-by-country/_benchmark"
    }
  },
  "records": 5,
  "time": 0.5,
  "containsErrors": false,
  "errorMessage": {}
}

Captured from the API examples test suite; ids and timestamps are normalized.

Embedded Query restriction

Benchmarking returns 400 Bad Request for an embedded Query. Only ad-hoc Queries can be benchmarked.

GET /api/queries/{id}/dataset

Read the caller's embedded Dataset for the Query.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Query id (UUID) or natural id

Response:

Responds 200 with the caller's embedded Dataset as HAL (created by a prior _run), or 404 if none exists yet. The Dataset is scoped to the current user, so each user has at most one embedded Dataset per Query.

Get the query’s embedded datasetGET /api/queries/admin:top-orders-by-country/dataset

GET /api/queries/{id}/dataset returns the caller’s embedded Dataset for the query (created by a prior _run), or 404 if none exists yet. It is scoped to the current user, so each user has at most one embedded dataset per query.

Response · 200

{
  "_links": {
    "self": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001"
    },
    "inf:draft": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/draft"
    },
    "inf:run": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_run"
    },
    "inf:benchmark": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_benchmark"
    },
    "inf:refresh": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_refresh"
    },
    "inf:data": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/data{?start,limit,q,sort,show,report}",
      "templated": true
    },
    "inf:user-settings": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/settings"
    },
    "inf:query": {
      "href": "https://informer.example.com/api/queries/00000000-0000-4000-8000-000000000002"
    },
    "inf:owner": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/owner"
    },
    "inf:search": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_search{?query,_source,sort,from,size,searchType,aggs,report,aggregations,alias,snapshots}",
      "templated": true
    },
    "inf:mapping": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/mapping"
    },
    "inf:job-templates": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/job-templates"
    },
    "inf:fields": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/fields"
    },
    "inf:count": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/count"
    },
    "inf:comments": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/comments"
    },
    "inf:visuals": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/visuals"
    },
    "inf:visual-templates": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/visual-templates"
    },
    "inf:dataset-tags": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/tags"
    },
    "inf:dataset-tag": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/tags/{tagId}",
      "templated": true
    },
    "inf:discover": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/discover"
    },
    "inf:filters": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/filters"
    },
    "inf:dataset-shares": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/shares"
    },
    "inf:flow": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/flow"
    },
    "inf:group": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/group"
    },
    "inf:group-rows": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/group-rows"
    },
    "inf:dataset-share": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/shares/{principalId}",
      "templated": true
    },
    "inf:import": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_import"
    },
    "inf:exceptions": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_exceptions"
    },
    "inf:search-aggregates": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_search-aggregates"
    },
    "inf:exporters": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/exporters"
    },
    "inf:favorite": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/favorite"
    },
    "inf:export-bundle": {
      "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/_export"
    },
    "edit": {
      "href": "https://informer.example.com/api/reports/00000000-0000-4000-8000-000000000001/_edit"
    }
  },
  "naturalId": "00000000-0000-4000-8000-000000000001",
  "permissions": {
    "edit": true,
    "share": true,
    "delete": true,
    "write": true,
    "addVisual": true,
    "deleteVisual": true,
    "changeOwner": true,
    "copy": true,
    "rename": true,
    "refresh": true,
    "modifyFlows": true,
    "replaceFile": true,
    "modifySettings": true,
    "createDataView": true,
    "assignTags": true,
    "createFilter": true,
    "scriptFields": true,
    "setIndex": false
  },
  "id": "00000000-0000-4000-8000-000000000001",
  "tenant": "acme",
  "ownerId": "admin",
  "slug": null,
  "name": null,
  "description": null,
  "embedded": true,
  "esIndex": "docsex.acme.00000000-0000-4000-8000-000000000001.1700000000000",
  "esIndexName": "00000000-0000-4000-8000-000000000001",
  "esType": "data",
  "records": 5,
  "size": "524288",
  "source": null,
  "sourceId": null,
  "params": {},
  "dataUpdatedAt": "2026-01-15T16:20:00.000Z",
  "dataExpiresAt": "2026-01-15T16:20:00.000Z",
  "ttl": 3600000,
  "append": false,
  "shared": false,
  "timestampField": null,
  "lastDurationMillis": "1500",
  "windowSize": 500,
  "settings": {},
  "flow": [],
  "esId": null,
  "lastQueriedAt": "2026-01-15T16:20:00.000Z",
  "esWorkers": 1,
  "datasetFieldReportAccess": false,
  "parentId": null,
  "templateProcessorId": null,
  "deleteDate": null,
  "createdAt": "2026-01-15T16:20:00.000Z",
  "updatedAt": "2026-01-15T16:20:00.000Z",
  "datasourceId": null,
  "reportId": null,
  "queryId": "00000000-0000-4000-8000-000000000002",
  "editingId": null,
  "folderId": null,
  "query": {
    "naturalId": "admin:top-orders-by-country",
    "fields": null,
    "permissions": {
      "assignTags": true,
      "changeOwner": true,
      "copy": true,
      "delete": true,
      "edit": true,
      "rename": true,
      "run": true,
      "share": true,
      "write": true
    },
    "id": "00000000-0000-4000-8000-000000000002",
    "tenant": "acme",
    "ownerId": "admin",
    "slug": "top-orders-by-country",
    "name": "Top Orders By Country",
    "description": "Northwind orders sorted by id, capped for examples",
    "shared": false,
    "embedded": false,
    "source": null,
    "sourceId": null,
    "settings": {},
    "inputs": null,
    "language": "sql",
    "flow": [],
    "payload": "SELECT o.\"OrderID\", o.\"CustomerID\", o.\"ShipCountry\", o.\"ShipCity\"\nFROM orders o\nORDER BY o.\"OrderID\"\nLIMIT 5",
    "defnUpdatedAt": null,
    "limit": -1,
    "createdAt": "2026-01-15T16:20:00.000Z",
    "updatedAt": "2026-01-15T16:20:00.000Z",
    "datasourceId": "00000000-0000-4000-8000-000000000003",
    "editingId": null,
    "folderId": null,
    "datasource": {
      "defaultLinkType": "sql",
      "aiSystemMessage": "This is a PostgresSQL database. Identifiers are case-sensitive by default. \n            Always surround all column names, table names, and schema names in double-quotes (\"). \n            For example:\n                SELECT \"OrderID\", \"ShipCountry\" FROM \"public\".\"orders\" WHERE \"ShipCity\" = 'Raleigh';\n            ---",
      "family": "sql",
      "languages": [
        "informer",
        "sql",
        "distinctValue",
        "… 2 more items (5 total) — omitted from docs"
      ],
      "naturalId": "admin:northwind",
      "image": "/opt/informer/packages/informer-server/modules/sql/images/postgres.svg",
      "compatibility": [],
      "permissions": {
        "assignTags": true,
        "edit": true,
        "delete": true,
        "share": true,
        "write": true,
        "changeOwner": true,
        "ping": true,
        "scan": true,
        "downloadSchema": true,
        "importData": true,
        "importSchema": true,
        "rename": true,
        "editConnection": true,
        "createLink": true,
        "setWrite": true,
        "createSuite": true,
        "createFieldExpression": true,
        "createMapping": false,
        "bundle": true,
        "query": true
      },
      "id": "00000000-0000-4000-8000-000000000003",
      "tenant": "acme",
      "ownerId": "admin",
      "slug": "northwind",
      "name": "Northwind",
      "description": null,
      "embedded": false,
      "type": "postgres",
      "connection": {
        "host": "localhost",
        "pool": {
          "max": 5,
          "min": 0,
          "idle": 10000,
          "acquire": 10000
        },
        "port": 5432,
        "user": "northwinduser",
        "database": "northwind",
        "password": "encrypted:iv:0000000000000000",
        "idleTimeoutMillis": 7
      },
      "scannedAt": "2026-01-15T16:20:00.000Z",
      "schemaUpdatedAt": "2026-01-15T16:20:00.000Z",
      "rescanRequired": false,
      "shared": false,
      "schemas": [
        "public"
      ],
      "source": null,
      "sourceId": null,
      "settings": {
        "multiSchema": false,
        "useFakeData": false,
        "remoteQueryBatchSize": {
          "multiKey": 500,
          "singleKey": 500
        },
        "usePreparedStatements": false
      },
      "data": null,
      "appId": null,
      "createdAt": "2026-01-15T16:20:00.000Z",
      "updatedAt": "2026-01-15T16:20:00.000Z",
      "folderId": null,
      "fileId": null,
      "shares": []
    }
  },
  "_embedded": {
    "inf:field": [
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/fields/CustomerID"
          }
        },
        "label": "Customer Id",
        "source": "Indexed",
        "id": "00000000-0000-4000-8000-000000000004",
        "tenant": "acme",
        "name": "CustomerID",
        "datasetId": "00000000-0000-4000-8000-000000000001",
        "position": 1,
        "dataType": "keyword_text",
        "script": null,
        "typeMapping": {
          "type": "keyword",
          "fields": {
            "text": {
              "type": "text"
            }
          },
          "ignore_above": 256
        },
        "formatOptions": null,
        "lockFieldId": false,
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "fieldId": null
      },
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/fields/OrderID"
          }
        },
        "label": "Order Id",
        "source": "Indexed",
        "id": "00000000-0000-4000-8000-000000000005",
        "tenant": "acme",
        "name": "OrderID",
        "datasetId": "00000000-0000-4000-8000-000000000001",
        "position": 0,
        "dataType": "float",
        "script": null,
        "typeMapping": {
          "type": "float"
        },
        "formatOptions": null,
        "lockFieldId": false,
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "fieldId": null
      },
      {
        "_links": {
          "self": {
            "href": "https://informer.example.com/api/datasets/00000000-0000-4000-8000-000000000001/fields/ShipCity"
          }
        },
        "label": "Ship City",
        "source": "Indexed",
        "id": "00000000-0000-4000-8000-000000000006",
        "tenant": "acme",
        "name": "ShipCity",
        "datasetId": "00000000-0000-4000-8000-000000000001",
        "position": 3,
        "dataType": "keyword_text",
        "script": null,
        "typeMapping": {
          "type": "keyword",
          "fields": {
            "text": {
              "type": "text"
            }
          },
          "ignore_above": 256
        },
        "formatOptions": null,
        "lockFieldId": false,
        "createdAt": "2026-01-15T16:20:00.000Z",
        "updatedAt": "2026-01-15T16:20:00.000Z",
        "fieldId": null
      },
      "… 1 more items (4 total) — omitted from docs"
    ],
    "inf:filter": []
  }
}

Captured from the API examples test suite; ids and timestamps are normalized.

Dataset lifecycle

An embedded Dataset is created when a Query is run. It persists until its TTL expires (default 60 minutes), the user runs the Query again with different parameters, or the Query definition is committed with clearAllUserSettings: true.

GET /api/queries/{id}/exporters

List the export formats eligible for the Query.

Authentication: Required

Path Parameters:

Parameter	Type	Description
`id`	string	Query id (UUID) or natural id

Response:

Responds 200 with a HAL collection (inf:query-exporters) of the dataset-export drivers eligible for this request, after applying the tenant's export-type restrictions. The set depends on the registered exporters and on tenant and license configuration.

List eligible export formatsGET /api/queries/admin:top-orders-by-country/exporters

GET /api/queries/{id}/exporters returns a HAL collection (inf:query-exporters) of the dataset-export drivers eligible for this request, after applying the tenant’s export-type restrictions. The set depends on registered exporters and tenant/license configuration.

Response · 200

[
  {
    "id": "csv",
    "label": "CSV",
    "icon": "flaticon-document111",
    "optsSchema": "… optsSchema (9 fields) omitted from docs",
    "editor": "csvEdit",
    "download": true,
    "extension": "csv",
    "contentType": "text/csv",
    "canApplyFilter": true,
    "canUseInJob": true,
    "canToggleFormatting": true,
    "applyFormatting": true,
    "allowEmbedded": true,
    "configSchema": "… configSchema (17 fields) omitted from docs"
  },
  {
    "id": "html",
    "label": "HTML",
    "icon": "flaticon-html",
    "editor": "htmlEdit",
    "contentType": "text/html",
    "extension": "html",
    "optsSchema": "… optsSchema (5 fields) omitted from docs",
    "download": true,
    "canApplyFilter": true,
    "canUseInJob": true,
    "canToggleFormatting": true,
    "applyFormatting": true,
    "allowEmbedded": true,
    "configSchema": "… configSchema (17 fields) omitted from docs"
  },
  {
    "id": "x-ms-iqy",
    "optsSchema": "… optsSchema (9 fields) omitted from docs",
    "editor": "iqyEdit",
    "contentType": "text/x-ms-iqy",
    "extension": "iqy",
    "canApplyFilter": false,
    "canUseInJob": false,
    "canToggleFormatting": false,
    "applyFormatting": true,
    "download": true,
    "allowEmbedded": true,
    "configSchema": "… configSchema (17 fields) omitted from docs"
  },
  "… 7 more items (10 total) — omitted from docs"
]

Captured from the API examples test suite; ids and timestamps are normalized.

Tenant restrictions

Available exporters can be restricted by tenant configuration. Some formats such as PDF or Excel may require additional licensing.

Execution Best Practices

Choosing the Right Endpoint

Use Case	Endpoint	Why
User wants to view and explore data	`POST /_run`	Persists a Dataset for filtering, sorting, and visualization
API needs raw data for integration	`POST /_execute`	Returns the rendered result without persistence overhead
Previewing a Query during design	`GET /sample`	Compiles only, with no `query:run` check
Measuring Query performance	`POST /_benchmark`	Times a full execution

Error Handling

Status	Cause	Resolution
`400`	`_run` or `_benchmark` called on an embedded Query	Refresh through the parent Dataset
`400`	Invalid parameters	Check the Query's inputs definition
`403`	Missing `query:run` permission	Confirm the caller can run the Query
`404`	No embedded Dataset yet (on `GET /dataset`)	Run the Query first with `_run`

Endpoint Overview​

POST /api/queries/{id}/_run​

POST /api/queries/{id}/_execute​

GET /api/queries/{id}/sample​

POST /api/queries/{id}/_benchmark​

GET /api/queries/{id}/dataset​

GET /api/queries/{id}/exporters​

Execution Best Practices​

Choosing the Right Endpoint​

Error Handling​

Endpoint Overview

POST /api/queries/{id}/_run

POST /api/queries/{id}/_execute

GET /api/queries/{id}/sample

POST /api/queries/{id}/_benchmark

GET /api/queries/{id}/dataset

GET /api/queries/{id}/exporters

Execution Best Practices

Choosing the Right Endpoint

Error Handling