Skip to Content

Data Retrieval

Ask a question

Ask a data question in plain words and get the SQL, the rows and a suggested chart.

POST
/api/v2/data-app/ask

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 TABLE tenancy. Datamarts with a schema or database per tenant are refused, because the call has no tenant.

Authorization

ServiceToken
headerAuthorizationBearer <token>

A service token. A data app API token is refused.

Body

Send question and at least one of datamartName or workspaceName.

questionstringrequired

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.

timezonestring

IANA time zone for dates. Default UTC

sessionIdstring

The sessionId of an earlier answer, to keep the conversation.

configobject

Follow-up settings.

1 field in config
followUpobject

{ "isEnable": true, "previousQuestion": "...", "previousSql": "..." } to ask a follow-up.

3 fields in followUp
isEnablebooleanrequired

true treats this question as a follow-up to the previous one.

The previous question.

Default: ""

The SQL of the previous answer.

Default: ""

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  }}
FieldDescription
dataThe rows
columnsWhich columns are dimensions and which are measures
queryThe SQL that ran
summaryA short answer in words
suggestedChartTypeA chart type that fits the rows
sessionIdSend it back for a follow-up

The response can have more fields, such as confidence, assumptions, chartSettings and verified.

Errors

Statuserror.codeWhy
400INVALID_REQUEST_BODYquestion is missing, neither name was sent, or nothing matched them
400INVALID_DATAMARTNo datamart has this name
400AUTHENTICATION_ERRORNo workspace has this name
400DATABASE_TENANCY_REQUIRES_CLIENTThe datamart has a schema or database per tenant
400WORKSPACE_HAS_NO_DATASOURCEThe workspace has no datasource
400NOT_DATA_QUESTIONThe question is not about your data
400QUERY_REFUSEDBryn would not run the query. The body has a refusal object that says why
403AUTHENTICATION_ERRORYou used a data app API token
503SEMANTIC_EXECUTION_FAILEDThe query failed. Try again
500INTERNAL_SERVER_ERRORQuery generation failed due to an internal error

For errors that every endpoint returns, see Authentication.

Example Request
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"}'
Example Response
{  "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"}