Gaur Docs

Reference for the contract query endpoint at POST /v1/api/{consumer_slug}/query.

Runs a structured query against a contract and returns governed, paginated rows. This is the REST query API. For a guided walkthrough, see Querying contracts.

Request

POST /v1/api/{consumer_slug}/query
Authorization: Bearer <api_key>
Content-Type: application/json

Path parameters

Parameter	Type	Description
`consumer_slug`	string	The slug of the consumer to query. The API key must authorize this consumer.

Body

Field	Type	Required	Description
`contract_name`	string	Yes	The contract to query. Must be linked to the consumer.
`query`	object	Yes	The query specification. See Query schema.
`context`	object	No	Key-value pairs for the contract's row-level security.

{
  "contract_name": "product_performance",
  "query": {
    "dimensions": [
      { "name": "ordered_at", "time_grain": "month" },
      { "name": "category" }
    ],
    "measures": ["revenue_usd", "cogs_ratio"],
    "filters": [{ "field": "category", "operator": "eq", "value": "jaffle" }],
    "sorts": [{ "field": "ordered_at", "direction": "asc" }],
    "limit": 100,
    "offset": 0
  },
  "context": { "store_id": "STR-008" }
}

The query object is documented field by field in the Query schema reference.

Response

200 OK with this body:

{
  "data": {
    "pagination": {
      "items": [
        { "ordered_at": "2026-04-01T00:00:00", "category": "jaffle", "revenue_usd": 84210.50, "cogs_ratio": 0.42 }
      ],
      "total_items":   12,
      "page":          1,
      "limit":         100,
      "total_pages":   1,
      "has_next_page": false,
      "has_prev_page": false
    },
    "execution_time_ms": 42
  },
  "message": null
}

Response fields

Field	Type	Description
`data.pagination.items`	array	The result rows. Each object is keyed by the requested dimensions and measures.
`data.pagination.total_items`	integer	Total rows across all pages.
`data.pagination.page`	integer	The current page number, starting at 1.
`data.pagination.limit`	integer	The page size actually applied.
`data.pagination.total_pages`	integer	Total number of pages.
`data.pagination.has_next_page`	boolean	Whether a page follows this one.
`data.pagination.has_prev_page`	boolean	Whether a page precedes this one.
`data.execution_time_ms`	integer	Query execution time in milliseconds.
`message`	string \| null	Optional informational message.

limit and offset in the query control paging. Gaur clamps limit to 10,000 rows; requests above that succeed but return 10,000 rows with pagination.limit: 10000 in the response. Always read data.pagination.limit to see the size that applied, and data.pagination.has_next_page to know whether to keep paging. See Pagination.

Status codes

Status	Meaning
`200`	Success.
`400`	Invalid input, or the query failed validation against the contract.
`401`	Missing or invalid API key.
`403`	The API key does not authorize this consumer, or the contract is not linked to it.
`404`	The named contract was not found.
`500`	Internal server error.

Error bodies follow the shape { "message": string, "code": string, "errors": string[] | null }. Branch on code, not on message.

Example

curl -X POST https://<base-url>/v1/api/jaffle-public/query \
  -H "Authorization: Bearer gaur_***************" \
  -H "Content-Type: application/json" \
  -d '{
    "contract_name": "product_performance",
    "query": { "measures": ["revenue_usd"], "limit": 1 }
  }'

Query endpoint