Query SQL
POST /v1/query/sqlRun a read-only SQL statement against the property warehouse. SELECT and
Same call over MCP
Read-only SQL on the warehousequery_sqlAuthenticate with an API key from the API & MCP Hub. The same call is available as an MCP tool at the same price.
Reference
What POST /v1/query/sql returns
This is the last resort. If a curated tool or query_semantic can answer the question, it will be cheaper and faster. UK only. You are charged if the query reaches the warehouse and then times out or errors there; a query rejected before it runs — bad SQL, an unreachable schema, a column that does not exist — is free, and the error says what to change.
Inputs
Before you call it
- sql
- The statement must be a single read-only SELECT or WITH over the marts_core, marts_facts, dimensions and location schemas. Bind values with :name placeholders and
paramsrather than interpolating them; the raw ingest schemas are not reachable.
Request
Calling POST /v1/query/sql
curl -X POST "https://api.marketcode.ai/v1/query/sql" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"sql":"SELECT count(*) AS sales FROM marts_core.transactions WHERE postcode_district = :district","params":{"district":"SE22"},"max_rows":5}'Send your API key as a Bearer token. Every response carries credits_charged and credits_remaining.
Inputs
Parameters
This endpoint takes no path or query parameters.
Request body
| Name | In | Type | Required | Description |
|---|---|---|---|---|
| sql | Body | string | Yes | A single read-only SELECT/WITH statement over the warehouse. |
| params | Body | object | No | Bound parameters, referenced as :name in the SQL. |
| max_rows | Body | integer | No | Row cap applied as an outer LIMIT (max 5000).Default: 1000 |
Response
What POST /v1/query/sql returns for a real request
curl -X POST "https://api.marketcode.ai/v1/query/sql" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"sql":"SELECT count(*) AS sales FROM marts_core.transactions WHERE postcode_district = :district","params":{"district":"SE22"},"max_rows":5}'{
"error": "HTTP 400",
"detail": "undefined column: column \"postcode_district\" does not exist. Column and table names must exist in the warehouse as written; the semantic endpoint (/property/se…"
}The call failed with these arguments; the status and message are shown rather than an invented body.
Price and licence
What it costs, and where the data comes from
Query SQL costs 25 credits per successful call over MCP and over REST, and the two surfaces share one credit balance.
You shape the query, so the price is fixed whatever it returns. A query rejected before it runs is free; you are charged once it reaches the warehouse, even if it then times out or errors there.
Credits are granted on sign-up and bought in packs; the pricing page lists every call.
Related
Endpoints used with Query SQL
FAQ
Questions about Query SQL
How much does `query_sql` cost?
+
Query SQL costs 25 credits per successful call over MCP and over REST, and the two surfaces share one credit balance. You shape the query, so the price is fixed whatever it returns. A query rejected before it runs is free; you are charged once it reaches the warehouse, even if it then times out or errors there.
How do I authenticate?
+
Send your API key as a Bearer token in the Authorization header. Keys are created in the API & MCP Hub, shown once and revocable. Every response carries the credits charged and your remaining balance.
Is there an MCP version?
+
Yes. The query_sql tool on the MarketCode MCP server is the same call at the same price, signed in with OAuth rather than a key, so Claude, ChatGPT, Codex and Cursor can run it in a conversation.
Where does the data come from?
+
The answer is computed by MarketCode. Coverage is the UK.
Does `query_sql` change anything?
+
No. The tool is annotated read-only on the server, so it never writes to your data or ours and an assistant can call it without a confirmation step.
Try Query SQL on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.