---
title: "Run a query"
method: POST
path: "/api/v1/query/run"
tags: ["query"]
---

# Run a query

`POST /api/v1/query/run`

## Request

- The document declares no server URL.
- Auth: one of:
  - API key in header `X-API-Key`
  - API key in header `Authorization`

Runs a read-only statement against a queryable source as the caller. The statement is planned first and refused unless the caller may query every table it references. Every attempt is recorded in the query log.

## Request body

- QueryRunInput
  - `max_rows` integer
  - `source` string, required
  - `statement` string, required

## Response `200`

OK

- QueryResult
  - `columns` QueryColumn[]
    - `name` string
    - `type` string
  - `context` QueryAssetContext[]
    - `asset_id` string
    - `description` string
    - `last_sync_at` string
    - `mrn` string
    - `name` string
    - `providers` string[]
    - `tags` string[]
    - `type` string
  - `query_id` string
  - `referenced_mrns` string[]
  - `row_count` integer
  - `rows` array[]
    - unknown[]
      - unknown
  - `truncated` boolean

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found

## Changes

> 65 revisions in range; 1 not diffed.

- **2026-10-22** `b5eb291dd2fe`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/marmotdata/apis/marmot-api/changes/api/v1/query/run/post.md)

---

[API](https://skmtc.dev/marmotdata/apis/marmot-api.md) - [All operations](https://skmtc.dev/marmotdata/apis/marmot-api/llms.txt) - [OpenAPI document](https://skmtc.dev/marmotdata/apis/marmot-api/revisions/18c57b576cb6?raw)