Governed semantic query
query_semanticRun a governed query against the semantic layer: choose an entity, then
Same call over REST
Query semantic/v1/query/semanticNot connected yet? Connect your assistant. Sign in with your MarketCode account; no API key needed.
Reference
What query_semantic answers
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.
Example
An example call to query_semantic
Use the MarketCode tool query_semantic with {"entity":"transactions","metrics":["median_price"],"dimensions":["postcode_district"],"filters":{"postcode_district":"SE22"},"limit":5} and show me the result.{
"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.
Inputs
Arguments query_semantic takes
| Name | Type | Required | Description |
|---|---|---|---|
| entity | string | Yes | |
| select | string[] | No | |
| metrics | string[] | No | |
| dimensions | string[] | No | |
| filters | any[] | No | |
| period | string | No | |
| joins | string[] | No | |
| order_by | any[] | No | |
| limit | integer | No | Default: 500 |
Usage
How to run query_semantic in your assistant
Ask your assistant in plain English, for example:
"Use the MarketCode tool query_semantic for <address or area>.
Show the result and the credits charged."
The arguments the assistant will send, for the example on this page:
{"entity":"transactions","metrics":["median_price"],"dimensions":["postcode_district"],"filters":{"postcode_district":"SE22"},"limit":5}The connect steps for Claude, ChatGPT, Codex, Cursor and Claude Code are on the MCP page.
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
Tools 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.
Which assistants can run `query_semantic`?
+
Any MCP client: Claude (claude.ai, Claude Desktop, Claude Code), ChatGPT in developer mode, Codex and Cursor, each documented on the MCP page. You sign in with your MarketCode account over OAuth; there is no key to paste, and the connection is read-only.
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 in your assistant.
30-minute call. We'll connect your assistant live on a real address.