Data Retrieval
Ask a question
Ask a data question in plain words and get the SQL, the rows and a suggested chart.
Bryn turns the question into SQL on a datamart or a workspace, runs it and returns the answer.
curl --request POST https://api.usedatabrain.com/api/v2/data-app/ask \ --header "Authorization: Bearer $DATABRAIN_SERVICE_TOKEN" \ --header "Content-Type: application/json" \ --data '{ "question": "Revenue by month this year", "datamartName": "Sales", "timezone": "America/New_York" }'Before you start
- You have a service token. A data app API token gets
403. See Authentication. - Each question uses AI credits of your plan.
- The datamart has no tenancy, or
TABLEtenancy. Datamarts with a schema or database per tenant are refused, because the call has no tenant.
ServiceTokenAuthorizationBearer <token>A service token. A data app API token is refused.
Body
Send question and at least one of datamartName or workspaceName.
The question.
Send this or the other one of the pair. The datamart to ask.
Send this or the other one of the pair. The workspace to ask.
IANA time zone for dates. Default UTC
The sessionId of an earlier answer, to keep the conversation.
Follow-up settings.
1 field in config
{ "isEnable": true, "previousQuestion": "...", "previousSql": "..." } to ask a follow-up.
3 fields in followUp
true treats this question as a follow-up to the previous one.
Accepted, but not used. Name the datamart or the workspace instead.
Response
{ "data": { "data": [{ "month": "2026-01", "revenue": 120400 }], "columns": { "dimensions": ["month"], "measures": ["revenue"] }, "query": "SELECT ...", "summary": "Revenue grew each month.", "suggestedChartType": "line", "reasoning": "...", "isTimeSeries": true, "sessionId": "5f6e7d8c-...", "timeTaken": 3120 }}| Field | Description |
|---|---|
data | The rows |
columns | Which columns are dimensions and which are measures |
query | The SQL that ran |
summary | A short answer in words |
suggestedChartType | A chart type that fits the rows |
sessionId | Send it back for a follow-up |
The response can have more fields, such as confidence, assumptions, chartSettings and verified.
Errors
| Status | error.code | Why |
|---|---|---|
| 400 | INVALID_REQUEST_BODY | question is missing, neither name was sent, or nothing matched them |
| 400 | INVALID_DATAMART | No datamart has this name |
| 400 | AUTHENTICATION_ERROR | No workspace has this name |
| 400 | DATABASE_TENANCY_REQUIRES_CLIENT | The datamart has a schema or database per tenant |
| 400 | WORKSPACE_HAS_NO_DATASOURCE | The workspace has no datasource |
| 400 | NOT_DATA_QUESTION | The question is not about your data |
| 400 | QUERY_REFUSED | Bryn would not run the query. The body has a refusal object that says why |
| 403 | AUTHENTICATION_ERROR | You used a data app API token |
| 503 | SEMANTIC_EXECUTION_FAILED | The query failed. Try again |
| 500 | INTERNAL_SERVER_ERROR | Query generation failed due to an internal error |
For errors that every endpoint returns, see Authentication.
curl -X POST 'https://api.usedatabrain.com/api/v2/data-app/ask' \ -H 'Content-Type: application/json' \ -d '{ "question": "Revenue by month this year", "datamartName": "Sales", "timezone": "America/New_York"}'{ "data": { "data": [ { "month": "2026-01", "revenue": 120400 } ], "columns": { "dimensions": [ "month" ], "measures": [ "revenue" ] }, "suggestedChartType": "line", "chartSettings": null, "chartTypeReason": null, "reasoning": "...", "confidence": null, "timeTaken": 3120, "sessionId": "5f6e7d8c-...", "summary": "Revenue grew each month.", "query": "SELECT ...", "isTimeSeries": true, "isCountryDimension": false, "questionType": null }, "_optionalKeys": "semantic, verified, verifyReason, assumptions, sqlFacts appear only when the pipeline reports them"}