Run a SQL query

Runs a read-only SQL query over the workspace’s records with the caller’s record access applied, and returns the rows as JSON with offset pagination in links and meta. A LIMIT or OFFSET in the SQL bounds the whole result, and page[offset] and page[limit] (up to 500) page within it. Each page reruns the query, so add an ORDER BY for stable pages. 64-bit integers, such as COUNT(*), come back as strings to keep their precision.

Authorization

Authorization<token>

API key authentication. Send your key in the Authorization header as: api-key <your-api-key>.

In: header

Path Parameters

workspace*string

The workspace slug — the {slug} segment of your Clarify workspace URL.

Query Parameters

page?

Offset pagination, e.g. page[offset]=0&page[limit]=100.

Default

{  "offset": 0,  "limit": 500}

sortOrder?

Sort order, e.g. sortOrder[column]=_created_at&sortOrder[dir]=DESC.

silent?boolean

When true, suppresses in-app and Slack notifications for this mutation.

Header Parameters

clarify-version?string

The API version for this request. Send 2026-01 to get the behavior documented here. Omit it to use your API key's version, which this header can raise but not lower.

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

sql*string

A read-only PostgreSQL SELECT over the workspace’s objects. Each object is a table (person, company, deal, c_*) and its fields are columns; the query runs with the caller’s record access applied.

Length1 <= length

Response Body

`application/json`

curl -X POST "https://example.com/workspaces/string/query" \  -H "clarify-version: 2026-01" \  -H "Content-Type: application/json" \  -d '{    "sql": "SELECT stage, COUNT(*) AS deals, SUM(amount) AS amount FROM deal GROUP BY stage ORDER BY amount DESC"  }'

{  "links": {    "next": null,    "prev": null  },  "meta": {    "total_records": 2,    "total_pages": 1,    "offset": 0,    "limit": 500  },  "data": [    {      "stage": "Won",      "deals": "4",      "amount": 182000    },    {      "stage": "In progress",      "deals": "7",      "amount": 96500    }  ]}