Query semantic
POST /v1/query/semanticRun a governed query against the semantic layer: choose an entity, then
Same call over MCP
Governed semantic queryquery_semanticAuthenticate 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/semantic returns
Prefer this over query_sql — it is cheaper, bounded, and self-describing. UK only. You are charged if the query reaches the warehouse and then times out or errors there; a rejected query is free.
Inputs
Before you call it
- entity
- An entity is a table in the semantic layer; metrics and dimensions are aliases the registry resolves to columns, so the query cannot reach anything the model does not expose. The response includes the SQL it generated.
Request
Calling POST /v1/query/semantic
curl -X POST "https://api.marketcode.ai/v1/query/semantic" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"entity":"transactions","metrics":["median_price"],"dimensions":["postcode_district"],"filters":{"postcode_district":"SE22"},"limit":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 |
|---|---|---|---|---|
| entity | Body | string | Yes | Semantic entity key, e.g. "area_facts" |
| select | Body | string[] | No | Column/dimension aliases |
| metrics | Body | string[] | No | Metric names on the entity |
| dimensions | Body | string[] | No | Group-by aliases |
| filters | Body | object[] | No | Filter clauses |
| period | Body | string | No | Period code, e.g. 2026-Q1 |
| joins | Body | string[] | No | Governed join target entities |
| order_by | Body | string[][] | No | [["alias","desc"], …] |
| limit | Body | integer | No | Row limit, capped at 2000Default: 500 |
Response
What POST /v1/query/semantic returns for a real request
curl -X POST "https://api.marketcode.ai/v1/query/semantic" \
-H "Authorization: Bearer $MARKETCODE_API_KEY"
-H "Content-Type: application/json" \
-d '{"entity":"transactions","metrics":["median_price"],"dimensions":["postcode_district"],"filters":{"postcode_district":"SE22"},"limit":5}'{
"error": "HTTP 422",
"detail": {
"error": "invalid_input",
"message": "One or more parameters were rejected. See `errors`.",
"errors": [
{
"field": "filters",
"message": "Input should be a valid list",
"type": "list_type"
}
],
"docs": "/v1/docs"
}
}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 semantic costs 10 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 semantic
FAQ
Questions about Query semantic
How much does `query_semantic` cost?
+
Query semantic costs 10 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_semantic 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_semantic` 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 semantic on a real address.
30-minute call. We'll provision a key and walk through the endpoint on your use case.