Skip to main content

Querying

AgentData answers questions two ways: natural language (let the planner figure out the query) and structured metric queries (you specify exactly what you want). Both run against your confirmed semantic model and both return the generated SQL alongside the data.

Natural language​

Best for ad-hoc questions, chat interfaces, and AI agents. Ask in any language.

curl -X POST https://agentdata.mdm.biskilled.com/api/query/nl \
  -H "Authorization: Bearer agentdata_sk_…" \
  -H "Content-Type: application/json" \
  -d '{"question": "top 5 products by revenue this year"}'

Response (shape):

{
  "data": [{ "product": "Côte de Blaye", "revenue": 141396.74 }, "…"],
  "row_count": 5,
  "generated_sql": ["SELECT …"],
  "planned_query": { "entity": "order_detail", "measures": ["revenue"], "…": "…" },
  "notes": [],
  "powered_by": "shim"
}

query_nl never hard-fails: if a question can't be mapped to the model, it returns an explanation in notes instead of an error — handy for conversational clients.

Structured metric query​

Best for apps, dashboards and pipelines where you want deterministic, precise control. In the app, pick an entity, then toggle the measures and dimensions you want and hit Run:

Metric query result

curl -X POST https://agentdata.mdm.biskilled.com/api/query/metric \
  -H "Authorization: Bearer agentdata_sk_…" \
  -H "Content-Type: application/json" \
  -d '{
        "entity": "order_detail",
        "measures": ["revenue"],
        "dimensions": ["product.name"],
        "filters": [{ "field": "order.year", "op": "=", "value": 2026 }],
        "order": [{ "field": "revenue", "dir": "desc" }],
        "limit": 5
      }'

Response includes data, row_count, generated_sql, engine and planned_query.

Validate without running​

Use POST /api/query/validate to check a structured query against the model without executing it — useful when building a query in a UI.

See it interactively​

The API Reference has a live console for every endpoint — add your API key and run real requests from the browser.

From an AI client​

If you'd rather not call the REST API directly, expose the same capabilities to Claude, ChatGPT or your IDE over the MCP server — the query_nl and query_metric tools map one-to-one to these endpoints.