---
title: "Query Dataset"
method: POST
path: "/v1/dataset/query"
tags: ["dataset-analysis"]
---

# Query Dataset

`POST /v1/dataset/query`

## Request

- Base URL: `https://api.pioneer.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.pioneer.ai/v1/dataset/query`
- Auth: one of:
  - API key in header `X-API-Key`
  - HTTP bearer
- TypeScript: <https://skmtc.dev/pioneer/apis/brain-api/docs/v1/dataset/query/post.ts> (a function with typed inputs; its response is checked against the schema)

Execute Polars code on a dataset server-side.

The code runs in a sandboxed environment with access to:
- `df`: Polars DataFrame containing the dataset
- `pl`: Polars module for expressions

Assign the result to a `result` variable to return it.
**Multiline code is fully supported** — use intermediate variables, comments, etc.

**Security**: Only allowlisted Polars DataFrame/Expression methods are
permitted. Control-flow (for/while/if-stmt), comprehensions, f-strings,
str.format, printf-style %-formatting (e.g. '%d' % x), imports, eval/exec,
and dunder access are all blocked.

**Examples**::

    result = df.head(10)

    filtered = df.filter(pl.col('score') > 0.5)
    grouped = filtered.group_by('label').agg([
        pl.col('score').mean().alias('avg_score'),
        pl.col('score').count().alias('count')
    ])
    result = grouped.sort('avg_score', descending=True)

## Request body

- DatasetQueryRequest: Request to execute Polars code on a dataset server-side. The code has access to: - `df`: Polars DataFrame containing the dataset - `pl`: Polars module for expressions (pl.col, pl.lit, pl.when, etc.) Assign result to `result` variable to return it. Multi-statement code with intermediate variables is supported. Control-flow (for/while/if-stmt), comprehensions, f-strings, and printf-style %-formatting (e.g. '%d' % x) are not available; use ternary expressions (A if cond else B) for conditional results.
  - `dataset_name` string, required: Name of the dataset to query
  - `version` string, nullable: Dataset version (latest if omitted)
  - `code` string, required: Polars code to execute. Access data as 'df'. Assign output to 'result'.
  - `timeout` integer: Execution timeout in seconds (1-120)
  - `max_rows_returned` integer: Maximum rows to return in result (1-100000)

## Response `200`

Successful Response

- DatasetQueryResponse: Response from dataset query execution.
  - `success` boolean, required
  - `dataset_name` string, required
  - `dataset_version` string, required
  - `result` unknown, required
  - `result_type` 'dataframe' | 'series' | 'scalar' | 'string' | 'list' | 'object' | 'none', required: Type of the returned result
  - `row_count` integer, nullable: Number of rows if result is a DataFrame
  - `columns` string[], nullable: Column names if result is a DataFrame
  - `execution_time_ms` integer, required: Execution time in milliseconds
  - `truncated` boolean: Whether result was truncated due to size limits
  - `message` string, required

## Other responses

- `422`: Validation Error

## Changes

- **2026-09-24** `0e5e86e2bae5`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/pioneer/apis/brain-api/changes/v1/dataset/query/post.md)

---

[API](https://skmtc.dev/pioneer/apis/brain-api.md) - [All operations](https://skmtc.dev/pioneer/apis/brain-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pioneer/apis/brain-api/revisions/0e5e86e2bae5?raw)