curl --request POST \
--url https://api.usedatabrain.com/api/v2/data-app/query \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
})
});
const data = await response.json();
console.log('Query results:', data.data.length, 'rows');
console.log('Time taken:', data.timeTaken, 'ms');
import requests
import json
url = "https://api.usedatabrain.com/api/v2/data-app/query"
headers = {
"Authorization": "Bearer dbn_live_abc123...",
"Content-Type": "application/json"
}
payload = {
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Query results: {len(data['data'])} rows")
print(f"Time taken: {data['timeTaken']} ms")
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/query')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer dbn_live_abc123...'
request['Content-Type'] = 'application/json'
request.body = {
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
}.to_json
response = http.request(request)
data = JSON.parse(response.body)
puts "Query results: #{data['data'].length} rows"
puts "Time taken: #{data['timeTaken']} ms"
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.HashMap;
public class DataBrainQueryAPI {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
ObjectMapper mapper = new ObjectMapper();
Map<String, Object> dashboardFilter = new HashMap<>();
Map<String, String> dateRange = new HashMap<>();
dateRange.put("start", "2024-01-01");
dateRange.put("end", "2024-01-31");
dashboardFilter.put("date_range", dateRange);
Map<String, Object> metricFilter = new HashMap<>();
metricFilter.put("region", "north-america");
Map<String, Object> requestBody = new HashMap<>();
requestBody.put("embedId", "embed_123");
requestBody.put("metricId", "metric_456");
requestBody.put("clientId", "user_789");
requestBody.put("dashboardFilter", dashboardFilter);
requestBody.put("metricFilter", metricFilter);
String jsonBody = mapper.writeValueAsString(requestBody);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/query"))
.header("Authorization", "Bearer dbn_live_abc123...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type QueryRequest struct {
EmbedId string `json:"embedId"`
MetricId string `json:"metricId"`
ClientId string `json:"clientId"`
DashboardFilter map[string]interface{} `json:"dashboardFilter,omitempty"`
MetricFilter map[string]interface{} `json:"metricFilter,omitempty"`
}
type QueryResponse struct {
Data []map[string]interface{} `json:"data"`
TimeTaken int `json:"timeTaken"`
TotalRecords int `json:"totalRecords"`
MetaData map[string]interface{} `json:"metaData"`
}
func main() {
reqBody := QueryRequest{
EmbedId: "embed_123",
MetricId: "metric_456",
ClientId: "user_789",
DashboardFilter: map[string]interface{}{
"date_range": map[string]string{
"start": "2024-01-01",
"end": "2024-01-31",
},
},
MetricFilter: map[string]interface{}{
"region": "north-america",
},
}
jsonData, _ := json.Marshal(reqBody)
req, _ := http.NewRequest("POST",
"https://api.usedatabrain.com/api/v2/data-app/query",
bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var queryResp QueryResponse
json.NewDecoder(resp.Body).Decode(&queryResp)
fmt.Printf("Query results: %d rows\n", len(queryResp.Data))
fmt.Printf("Time taken: %d ms\n", queryResp.TimeTaken)
}
<?php
$url = 'https://api.usedatabrain.com/api/v2/data-app/query';
$data = [
'embedId' => 'embed_123',
'metricId' => 'metric_456',
'clientId' => 'user_789',
'dashboardFilter' => [
'date_range' => [
'start' => '2024-01-01',
'end' => '2024-01-31'
]
],
'metricFilter' => [
'region' => 'north-america'
]
];
$options = [
'http' => [
'header' => [
'Authorization: Bearer dbn_live_abc123...',
'Content-Type: application/json'
],
'method' => 'POST',
'content' => json_encode($data)
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
echo "Query results: " . count($response['data']) . " rows\n";
echo "Time taken: " . $response['timeTaken'] . " ms\n";
?>
{
"data": [
{
"date": "2024-01-01",
"revenue": 15000,
"region": "north-america",
"customer_count": 45
},
{
"date": "2024-01-02",
"revenue": 18500,
"region": "north-america",
"customer_count": 52
},
{
"date": "2024-01-03",
"revenue": 16500,
"region": "north-america",
"customer_count": 138
}
],
"timeTaken": 245,
"comparisonValue": 12500,
"totalRecords": 31,
"metaData": {
"columns": [
{
"name": "date",
"dataType": "date"
},
{
"name": "revenue",
"dataType": "number"
},
{
"name": "region",
"dataType": "string"
},
{
"name": "customer_count",
"dataType": "number"
}
],
"groupbyColumnList": ["date", "region"]
},
"metricid": "metric_456",
"error": null
}
{
"data": [],
"timeTaken": 45,
"totalRecords": 0,
"metaData": {
"columns": [],
"groupbyColumnList": []
},
"metricid": "metric_456",
"error": null
}
{
"error": {
"code": "INVALID_DATA_APP_API_KEY",
"message": "Invalid or missing Data App API Key"
}
}
{
"error": {
"code": "INVALID_EMBED_ID",
"message": "Embed ID not found or access denied",
"status": 400
}
}
{
"error": {
"code": "EMBED_PARAM_ERROR",
"message": "Embed ID not found or mismatched with API Key"
}
}
curl --request POST \
--url https://api.usedatabrain.com/api/v2/data-app/query \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
})
});
const data = await response.json();
console.log('Query results:', data.data.length, 'rows');
console.log('Time taken:', data.timeTaken, 'ms');
import requests
import json
url = "https://api.usedatabrain.com/api/v2/data-app/query"
headers = {
"Authorization": "Bearer dbn_live_abc123...",
"Content-Type": "application/json"
}
payload = {
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Query results: {len(data['data'])} rows")
print(f"Time taken: {data['timeTaken']} ms")
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/query')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer dbn_live_abc123...'
request['Content-Type'] = 'application/json'
request.body = {
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
}.to_json
response = http.request(request)
data = JSON.parse(response.body)
puts "Query results: #{data['data'].length} rows"
puts "Time taken: #{data['timeTaken']} ms"
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.HashMap;
public class DataBrainQueryAPI {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
ObjectMapper mapper = new ObjectMapper();
Map<String, Object> dashboardFilter = new HashMap<>();
Map<String, String> dateRange = new HashMap<>();
dateRange.put("start", "2024-01-01");
dateRange.put("end", "2024-01-31");
dashboardFilter.put("date_range", dateRange);
Map<String, Object> metricFilter = new HashMap<>();
metricFilter.put("region", "north-america");
Map<String, Object> requestBody = new HashMap<>();
requestBody.put("embedId", "embed_123");
requestBody.put("metricId", "metric_456");
requestBody.put("clientId", "user_789");
requestBody.put("dashboardFilter", dashboardFilter);
requestBody.put("metricFilter", metricFilter);
String jsonBody = mapper.writeValueAsString(requestBody);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/query"))
.header("Authorization", "Bearer dbn_live_abc123...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type QueryRequest struct {
EmbedId string `json:"embedId"`
MetricId string `json:"metricId"`
ClientId string `json:"clientId"`
DashboardFilter map[string]interface{} `json:"dashboardFilter,omitempty"`
MetricFilter map[string]interface{} `json:"metricFilter,omitempty"`
}
type QueryResponse struct {
Data []map[string]interface{} `json:"data"`
TimeTaken int `json:"timeTaken"`
TotalRecords int `json:"totalRecords"`
MetaData map[string]interface{} `json:"metaData"`
}
func main() {
reqBody := QueryRequest{
EmbedId: "embed_123",
MetricId: "metric_456",
ClientId: "user_789",
DashboardFilter: map[string]interface{}{
"date_range": map[string]string{
"start": "2024-01-01",
"end": "2024-01-31",
},
},
MetricFilter: map[string]interface{}{
"region": "north-america",
},
}
jsonData, _ := json.Marshal(reqBody)
req, _ := http.NewRequest("POST",
"https://api.usedatabrain.com/api/v2/data-app/query",
bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var queryResp QueryResponse
json.NewDecoder(resp.Body).Decode(&queryResp)
fmt.Printf("Query results: %d rows\n", len(queryResp.Data))
fmt.Printf("Time taken: %d ms\n", queryResp.TimeTaken)
}
<?php
$url = 'https://api.usedatabrain.com/api/v2/data-app/query';
$data = [
'embedId' => 'embed_123',
'metricId' => 'metric_456',
'clientId' => 'user_789',
'dashboardFilter' => [
'date_range' => [
'start' => '2024-01-01',
'end' => '2024-01-31'
]
],
'metricFilter' => [
'region' => 'north-america'
]
];
$options = [
'http' => [
'header' => [
'Authorization: Bearer dbn_live_abc123...',
'Content-Type: application/json'
],
'method' => 'POST',
'content' => json_encode($data)
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
echo "Query results: " . count($response['data']) . " rows\n";
echo "Time taken: " . $response['timeTaken'] . " ms\n";
?>
{
"data": [
{
"date": "2024-01-01",
"revenue": 15000,
"region": "north-america",
"customer_count": 45
},
{
"date": "2024-01-02",
"revenue": 18500,
"region": "north-america",
"customer_count": 52
},
{
"date": "2024-01-03",
"revenue": 16500,
"region": "north-america",
"customer_count": 138
}
],
"timeTaken": 245,
"comparisonValue": 12500,
"totalRecords": 31,
"metaData": {
"columns": [
{
"name": "date",
"dataType": "date"
},
{
"name": "revenue",
"dataType": "number"
},
{
"name": "region",
"dataType": "string"
},
{
"name": "customer_count",
"dataType": "number"
}
],
"groupbyColumnList": ["date", "region"]
},
"metricid": "metric_456",
"error": null
}
{
"data": [],
"timeTaken": 45,
"totalRecords": 0,
"metaData": {
"columns": [],
"groupbyColumnList": []
},
"metricid": "metric_456",
"error": null
}
{
"error": {
"code": "INVALID_DATA_APP_API_KEY",
"message": "Invalid or missing Data App API Key"
}
}
{
"error": {
"code": "INVALID_EMBED_ID",
"message": "Embed ID not found or access denied",
"status": 400
}
}
{
"error": {
"code": "EMBED_PARAM_ERROR",
"message": "Embed ID not found or mismatched with API Key"
}
}
Data Retrieval
Fetch metric data by data app
Execute queries on metrics within your embedded dashboards and retrieve the resulting data.
curl --request POST \
--url https://api.usedatabrain.com/api/v2/data-app/query \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
})
});
const data = await response.json();
console.log('Query results:', data.data.length, 'rows');
console.log('Time taken:', data.timeTaken, 'ms');
import requests
import json
url = "https://api.usedatabrain.com/api/v2/data-app/query"
headers = {
"Authorization": "Bearer dbn_live_abc123...",
"Content-Type": "application/json"
}
payload = {
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Query results: {len(data['data'])} rows")
print(f"Time taken: {data['timeTaken']} ms")
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/query')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer dbn_live_abc123...'
request['Content-Type'] = 'application/json'
request.body = {
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
}.to_json
response = http.request(request)
data = JSON.parse(response.body)
puts "Query results: #{data['data'].length} rows"
puts "Time taken: #{data['timeTaken']} ms"
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.HashMap;
public class DataBrainQueryAPI {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
ObjectMapper mapper = new ObjectMapper();
Map<String, Object> dashboardFilter = new HashMap<>();
Map<String, String> dateRange = new HashMap<>();
dateRange.put("start", "2024-01-01");
dateRange.put("end", "2024-01-31");
dashboardFilter.put("date_range", dateRange);
Map<String, Object> metricFilter = new HashMap<>();
metricFilter.put("region", "north-america");
Map<String, Object> requestBody = new HashMap<>();
requestBody.put("embedId", "embed_123");
requestBody.put("metricId", "metric_456");
requestBody.put("clientId", "user_789");
requestBody.put("dashboardFilter", dashboardFilter);
requestBody.put("metricFilter", metricFilter);
String jsonBody = mapper.writeValueAsString(requestBody);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/query"))
.header("Authorization", "Bearer dbn_live_abc123...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type QueryRequest struct {
EmbedId string `json:"embedId"`
MetricId string `json:"metricId"`
ClientId string `json:"clientId"`
DashboardFilter map[string]interface{} `json:"dashboardFilter,omitempty"`
MetricFilter map[string]interface{} `json:"metricFilter,omitempty"`
}
type QueryResponse struct {
Data []map[string]interface{} `json:"data"`
TimeTaken int `json:"timeTaken"`
TotalRecords int `json:"totalRecords"`
MetaData map[string]interface{} `json:"metaData"`
}
func main() {
reqBody := QueryRequest{
EmbedId: "embed_123",
MetricId: "metric_456",
ClientId: "user_789",
DashboardFilter: map[string]interface{}{
"date_range": map[string]string{
"start": "2024-01-01",
"end": "2024-01-31",
},
},
MetricFilter: map[string]interface{}{
"region": "north-america",
},
}
jsonData, _ := json.Marshal(reqBody)
req, _ := http.NewRequest("POST",
"https://api.usedatabrain.com/api/v2/data-app/query",
bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var queryResp QueryResponse
json.NewDecoder(resp.Body).Decode(&queryResp)
fmt.Printf("Query results: %d rows\n", len(queryResp.Data))
fmt.Printf("Time taken: %d ms\n", queryResp.TimeTaken)
}
<?php
$url = 'https://api.usedatabrain.com/api/v2/data-app/query';
$data = [
'embedId' => 'embed_123',
'metricId' => 'metric_456',
'clientId' => 'user_789',
'dashboardFilter' => [
'date_range' => [
'start' => '2024-01-01',
'end' => '2024-01-31'
]
],
'metricFilter' => [
'region' => 'north-america'
]
];
$options = [
'http' => [
'header' => [
'Authorization: Bearer dbn_live_abc123...',
'Content-Type: application/json'
],
'method' => 'POST',
'content' => json_encode($data)
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
echo "Query results: " . count($response['data']) . " rows\n";
echo "Time taken: " . $response['timeTaken'] . " ms\n";
?>
{
"data": [
{
"date": "2024-01-01",
"revenue": 15000,
"region": "north-america",
"customer_count": 45
},
{
"date": "2024-01-02",
"revenue": 18500,
"region": "north-america",
"customer_count": 52
},
{
"date": "2024-01-03",
"revenue": 16500,
"region": "north-america",
"customer_count": 138
}
],
"timeTaken": 245,
"comparisonValue": 12500,
"totalRecords": 31,
"metaData": {
"columns": [
{
"name": "date",
"dataType": "date"
},
{
"name": "revenue",
"dataType": "number"
},
{
"name": "region",
"dataType": "string"
},
{
"name": "customer_count",
"dataType": "number"
}
],
"groupbyColumnList": ["date", "region"]
},
"metricid": "metric_456",
"error": null
}
{
"data": [],
"timeTaken": 45,
"totalRecords": 0,
"metaData": {
"columns": [],
"groupbyColumnList": []
},
"metricid": "metric_456",
"error": null
}
{
"error": {
"code": "INVALID_DATA_APP_API_KEY",
"message": "Invalid or missing Data App API Key"
}
}
{
"error": {
"code": "INVALID_EMBED_ID",
"message": "Embed ID not found or access denied",
"status": 400
}
}
{
"error": {
"code": "EMBED_PARAM_ERROR",
"message": "Embed ID not found or mismatched with API Key"
}
}
POST
/
api
/
v2
/
data-app
/
query
curl --request POST \
--url https://api.usedatabrain.com/api/v2/data-app/query \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}'
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/query', {
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_abc123...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
})
});
const data = await response.json();
console.log('Query results:', data.data.length, 'rows');
console.log('Time taken:', data.timeTaken, 'ms');
import requests
import json
url = "https://api.usedatabrain.com/api/v2/data-app/query"
headers = {
"Authorization": "Bearer dbn_live_abc123...",
"Content-Type": "application/json"
}
payload = {
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
},
"metricFilter": {
"region": "north-america"
}
}
response = requests.post(url, headers=headers, data=json.dumps(payload))
data = response.json()
print(f"Query results: {len(data['data'])} rows")
print(f"Time taken: {data['timeTaken']} ms")
require 'net/http'
require 'json'
uri = URI('https://api.usedatabrain.com/api/v2/data-app/query')
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true
request = Net::HTTP::Post.new(uri)
request['Authorization'] = 'Bearer dbn_live_abc123...'
request['Content-Type'] = 'application/json'
request.body = {
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789',
dashboardFilter: {
date_range: {
start: '2024-01-01',
end: '2024-01-31'
}
},
metricFilter: {
region: 'north-america'
}
}.to_json
response = http.request(request)
data = JSON.parse(response.body)
puts "Query results: #{data['data'].length} rows"
puts "Time taken: #{data['timeTaken']} ms"
import java.net.http.HttpClient;
import java.net.http.HttpRequest;
import java.net.http.HttpResponse;
import java.net.URI;
import com.fasterxml.jackson.databind.ObjectMapper;
import java.util.Map;
import java.util.HashMap;
public class DataBrainQueryAPI {
public static void main(String[] args) throws Exception {
HttpClient client = HttpClient.newHttpClient();
ObjectMapper mapper = new ObjectMapper();
Map<String, Object> dashboardFilter = new HashMap<>();
Map<String, String> dateRange = new HashMap<>();
dateRange.put("start", "2024-01-01");
dateRange.put("end", "2024-01-31");
dashboardFilter.put("date_range", dateRange);
Map<String, Object> metricFilter = new HashMap<>();
metricFilter.put("region", "north-america");
Map<String, Object> requestBody = new HashMap<>();
requestBody.put("embedId", "embed_123");
requestBody.put("metricId", "metric_456");
requestBody.put("clientId", "user_789");
requestBody.put("dashboardFilter", dashboardFilter);
requestBody.put("metricFilter", metricFilter);
String jsonBody = mapper.writeValueAsString(requestBody);
HttpRequest request = HttpRequest.newBuilder()
.uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/query"))
.header("Authorization", "Bearer dbn_live_abc123...")
.header("Content-Type", "application/json")
.POST(HttpRequest.BodyPublishers.ofString(jsonBody))
.build();
HttpResponse<String> response = client.send(request,
HttpResponse.BodyHandlers.ofString());
System.out.println("Response: " + response.body());
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"net/http"
)
type QueryRequest struct {
EmbedId string `json:"embedId"`
MetricId string `json:"metricId"`
ClientId string `json:"clientId"`
DashboardFilter map[string]interface{} `json:"dashboardFilter,omitempty"`
MetricFilter map[string]interface{} `json:"metricFilter,omitempty"`
}
type QueryResponse struct {
Data []map[string]interface{} `json:"data"`
TimeTaken int `json:"timeTaken"`
TotalRecords int `json:"totalRecords"`
MetaData map[string]interface{} `json:"metaData"`
}
func main() {
reqBody := QueryRequest{
EmbedId: "embed_123",
MetricId: "metric_456",
ClientId: "user_789",
DashboardFilter: map[string]interface{}{
"date_range": map[string]string{
"start": "2024-01-01",
"end": "2024-01-31",
},
},
MetricFilter: map[string]interface{}{
"region": "north-america",
},
}
jsonData, _ := json.Marshal(reqBody)
req, _ := http.NewRequest("POST",
"https://api.usedatabrain.com/api/v2/data-app/query",
bytes.NewBuffer(jsonData))
req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
req.Header.Set("Content-Type", "application/json")
client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
panic(err)
}
defer resp.Body.Close()
var queryResp QueryResponse
json.NewDecoder(resp.Body).Decode(&queryResp)
fmt.Printf("Query results: %d rows\n", len(queryResp.Data))
fmt.Printf("Time taken: %d ms\n", queryResp.TimeTaken)
}
<?php
$url = 'https://api.usedatabrain.com/api/v2/data-app/query';
$data = [
'embedId' => 'embed_123',
'metricId' => 'metric_456',
'clientId' => 'user_789',
'dashboardFilter' => [
'date_range' => [
'start' => '2024-01-01',
'end' => '2024-01-31'
]
],
'metricFilter' => [
'region' => 'north-america'
]
];
$options = [
'http' => [
'header' => [
'Authorization: Bearer dbn_live_abc123...',
'Content-Type: application/json'
],
'method' => 'POST',
'content' => json_encode($data)
]
];
$context = stream_context_create($options);
$result = file_get_contents($url, false, $context);
$response = json_decode($result, true);
echo "Query results: " . count($response['data']) . " rows\n";
echo "Time taken: " . $response['timeTaken'] . " ms\n";
?>
{
"data": [
{
"date": "2024-01-01",
"revenue": 15000,
"region": "north-america",
"customer_count": 45
},
{
"date": "2024-01-02",
"revenue": 18500,
"region": "north-america",
"customer_count": 52
},
{
"date": "2024-01-03",
"revenue": 16500,
"region": "north-america",
"customer_count": 138
}
],
"timeTaken": 245,
"comparisonValue": 12500,
"totalRecords": 31,
"metaData": {
"columns": [
{
"name": "date",
"dataType": "date"
},
{
"name": "revenue",
"dataType": "number"
},
{
"name": "region",
"dataType": "string"
},
{
"name": "customer_count",
"dataType": "number"
}
],
"groupbyColumnList": ["date", "region"]
},
"metricid": "metric_456",
"error": null
}
{
"data": [],
"timeTaken": 45,
"totalRecords": 0,
"metaData": {
"columns": [],
"groupbyColumnList": []
},
"metricid": "metric_456",
"error": null
}
{
"error": {
"code": "INVALID_DATA_APP_API_KEY",
"message": "Invalid or missing Data App API Key"
}
}
{
"error": {
"code": "INVALID_EMBED_ID",
"message": "Embed ID not found or access denied",
"status": 400
}
}
{
"error": {
"code": "EMBED_PARAM_ERROR",
"message": "Embed ID not found or mismatched with API Key"
}
}
Query specific metrics from your embedded dashboards to retrieve data programmatically. This endpoint allows you to fetch metric data with optional filtering and is essential for building custom analytics interfaces or exporting data from your embedded dashboards.
Use this endpoint for all new integrations. This is the recommended endpoint format.This endpoint still works but will be deprecated. Please migrate to the new endpoint format.
Endpoint Migration Notice: We’re transitioning to kebab-case endpoints. The new endpoint is
/api/v2/data-app/query. The old endpoint /api/v2/dataApp/query will be deprecated soon. Please update your integrations to use the new endpoint format.This endpoint requires an embed ID, metric ID, and client ID. The metric must be associated with the specified embed configuration for the query to succeed.
Endpoint Formats
- New Endpoint (Recommended)
- Legacy Endpoint (Deprecated Soon)
POST https://api.usedatabrain.com/api/v2/data-app/query
POST https://api.usedatabrain.com/api/v2/dataApp/query
Authentication
All API requests must include your API key in the Authorization header. Get your API token when creating a data app - see our data app creation guide for details. Finding your API token: For detailed instructions, see the API Token guide.Headers
string
required
Bearer token for API authentication. Use your API key from the data app.
Authorization: Bearer dbn_live_abc123...
string
required
Must be set to
application/json for all requests.Content-Type: application/json
Request Body
string
required
The unique identifier of the embed configuration containing the metric.
Show Finding embed IDs
Show Finding embed IDs
- Use the List All Embeds API to get embed IDs
- Check the response from embed creation
- Available in the DataBrain dashboard when viewing embed configurations
string
required
The unique identifier of the metric to query.
Show Finding metric IDs
Show Finding metric IDs
- Available in the metric URL:
/metric/{metricId} - Retrieved via the Fetch Metrics by Embed API
- Found in the DataBrain dashboard when viewing a metric
string
required
Unique identifier for the end user making the query. Used for row-level security and access control.
Show Client ID usage
Show Client ID usage
- Should match the clientId used in guest token generation
- Used for applying row-level security filters
- Consistent across user sessions
- Enables multi-tenant data isolation
object
Dashboard-level filters to apply to the metric query. These filters affect the entire dashboard context.
Show Dashboard filter examples
Show Dashboard filter examples
{
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
},
"region": "north-america",
"product_category": "electronics"
}
object
Metric-specific filters to apply to the query. Used for row-level security and additional filtering.
Show Metric filter examples
Show Metric filter examples
{
"customer_segment": "enterprise",
"product_category": "software",
"status": "active"
}
string
Optional string. Use when the dashboard’s workspace is configured for multiple datasources (
MULTI_DATASOURCE): pass the datasource name (as in Data Studio / your integration credentials) so the query runs against that datasource. If the name does not resolve, the API returns DATASOURCE_NAME_ERROR (400).Show Details
Show Details
- Not used for multi-datamart workspaces; use
dataMartNameinstead when applicable - For workspaces that are not multi-datasource, omit this field unless your integration already relies on it
string
Optional string. Use the exact JSON property name
dataMartName (camelCase with a capital M in Mart).When the dashboard’s workspace is configured for multiple datamarts (MULTI_DATAMART), pass the datamart name so the query resolves that datamart’s linked datasource. Names follow the same rules as in the List Datamarts API. If the name does not resolve, the API returns DATAMART_NAME_ERROR (400).Show Details
Show Details
- Not used for multi-datasource workspaces; use
datasourceNameinstead when applicable - Distinct from workspace create/update body field
datamartName(different casing for this endpoint)
Response
array
Array of objects containing the query results. Each object represents a row of data with column names as keys.
Example
[
{
"date": "2024-01-01",
"revenue": 15000,
"region": "north-america"
},
{
"date": "2024-01-02",
"revenue": 18000,
"region": "north-america"
}
]
number
Query execution time in milliseconds.
number
Comparison value for metrics with comparison enabled.
number
Total number of records in the result set.
object
string
The metric ID that was queried (echo of request parameter).
null | object
Error object if the request failed, otherwise
null for successful requests.Examples
Error Codes
string
Invalid embed ID - The specified embed ID doesn’t exist or you don’t have access
string
Invalid metric ID - The specified metric ID doesn’t exist or isn’t associated with the embed
string
Missing or invalid data app - Check your API key and data app configuration
string
Embed ID error - The embed ID was not found or doesn’t match the API key being used
string
Metric not found - The specified metric ID doesn’t exist or isn’t associated with the embed configuration
string
Invalid datasource name - The specified datasource name could not be resolved for a multi-datasource workspace
string
Invalid datamart name - The specified
dataMartName could not be resolved for a multi-datamart workspaceHTTP Status Code Summary
| Status Code | Description |
|---|---|
200 | OK - Query executed successfully |
400 | Bad Request - Invalid request parameters or missing required fields |
401 | Unauthorized - Invalid or expired API token |
404 | Not Found - Embed ID or metric ID not found |
429 | Too Many Requests - Rate limit exceeded |
500 | Internal Server Error - Unexpected server error |
Possible Errors
| Error Code | HTTP Status | Description |
|---|---|---|
INVALID_EMBED_ID | 400 | Embed ID not found |
INVALID_METRIC_ID | 400 | Invalid metric ID |
INVALID_DATA_APP_API_KEY | 401 | Missing or invalid data app |
EMBED_PARAM_ERROR | 404 | Embed ID error |
METRIC_NOT_FOUND | 404 | Metric not found |
DATASOURCE_NAME_ERROR | 400 | Invalid datasource name (multi-datasource) |
DATAMART_NAME_ERROR | 400 | Invalid datamart name (multi-datamart) |
RATE_LIMIT_EXCEEDED | 429 | Too many requests |
INTERNAL_SERVER_ERROR | 500 | Unexpected failure |
Filtering Guide
Dashboard Filters
Dashboard filters apply to the entire dashboard context and affect all metrics. Common use cases include:- Date range filtering: Limit data to specific time periods
- Category filtering: Filter by region, department, product line, etc.
- Global parameters: Set values that affect multiple metrics
Example
{
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-03-31"
},
"region": "north-america",
"product_category": "electronics"
}
}
Metric Filters
Metric filters apply specifically to the metric being queried and can be used for:- Row-level security (RLS): Restrict data based on client permissions
- Additional filtering: Apply metric-specific conditions
- Client isolation: Ensure multi-tenant data separation
Example
{
"metricFilter": {
"department": "sales",
"status": "active",
"client_group": "enterprise"
}
}
Use Cases
Export Dashboard Data
async function exportDashboardData(embedId, clientId) {
// Get all metrics
const metricsResponse = await fetch(
`https://api.usedatabrain.com/api/v2/data-app/metrics?embedId=${embedId}&clientId=${clientId}`,
{
headers: { 'Authorization': 'Bearer dbn_live_...' }
}
);
const { data: metrics } = await metricsResponse.json();
// Query each metric
const allData = {};
for (const metric of metrics) {
const queryResponse = await fetch(
'https://api.usedatabrain.com/api/v2/data-app/query',
{
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
embedId,
metricId: metric.metricId,
clientId
})
}
);
const queryResult = await queryResponse.json();
allData[metric.name] = queryResult.data;
}
return allData;
}
Real-time Data Refresh
async function refreshMetricData(embedId, metricId, clientId, filters) {
const response = await fetch(
'https://api.usedatabrain.com/api/v2/data-app/query',
{
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
embedId,
metricId,
clientId,
dashboardFilter: filters
})
}
);
return await response.json();
}
// Refresh every 5 minutes
setInterval(async () => {
const data = await refreshMetricData(
'embed_123',
'metric_456',
'user_789',
{ date_range: { start: 'today', end: 'today' } }
);
updateDashboard(data);
}, 5 * 60 * 1000);
Multi-Tenant Data Access
async function getClientMetricData(embedId, metricId, clientId) {
// Apply client-specific filters automatically
const response = await fetch(
'https://api.usedatabrain.com/api/v2/data-app/query',
{
method: 'POST',
headers: {
'Authorization': 'Bearer dbn_live_...',
'Content-Type': 'application/json'
},
body: JSON.stringify({
embedId,
metricId,
clientId,
metricFilter: {
// RLS ensures clients only see their data
client_id: clientId
}
})
}
);
return await response.json();
}
Best Practices
- Cache responses - Cache query results when appropriate to reduce API calls and improve performance
- Use filters efficiently - Apply filters at the query level rather than filtering data client-side
- Handle pagination - For large datasets, implement pagination or limit results
- Error handling - Implement robust error handling and retry logic
- Rate limiting - Respect rate limits and implement exponential backoff
- Security - Never expose API keys in client-side code; proxy requests through your backend
Performance Tips
- Minimize filter complexity - Complex filters can slow down queries
- Request only needed columns - If possible, select only required columns
- Use date ranges - Limit queries to specific time periods
- Cache when possible - Cache frequently accessed data
- Batch requests - When querying multiple metrics, consider batching requests
Quick Start Guide
1
Get embed and metric IDs
First, get your embed ID and metric ID from your DataBrain dashboard or via the List APIs:
# List your embeds to find the embedId
curl --request GET \
--url https://api.usedatabrain.com/api/v2/data-app/embeds \
--header 'Authorization: Bearer dbn_live_abc123...'
2
Fetch available metrics
Use the Fetch Metrics by Embed endpoint to get a list of available metrics:
curl --request GET \
--url 'https://api.usedatabrain.com/api/v2/data-app/metrics?embedId=embed_123&clientId=user_789' \
--header 'Authorization: Bearer dbn_live_abc123...'
3
Make your first query
Query a metric with minimal parameters:
curl --request POST \
--url https://api.usedatabrain.com/api/v2/data-app/query \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789"
}'
4
Add filters for specific data
Include filters to narrow down your results:
curl --request POST \
--url https://api.usedatabrain.com/api/v2/data-app/query \
--header 'Authorization: Bearer dbn_live_abc123...' \
--header 'Content-Type: application/json' \
--data '{
"embedId": "embed_123",
"metricId": "metric_456",
"clientId": "user_789",
"dashboardFilter": {
"date_range": {
"start": "2024-01-01",
"end": "2024-01-31"
}
}
}'
5
Process the results
Use the returned data in your application:
const queryData = await queryMetric({
embedId: 'embed_123',
metricId: 'metric_456',
clientId: 'user_789'
});
console.log(`Found ${queryData.totalRecords} records`);
console.log(`Query took ${queryData.timeTaken}ms`);
queryData.data.forEach(row => {
// Process each data row
console.log(row);
});
Next Steps
Fetch Metrics by Embed
Get a list of available metrics before querying
Fetch Dashboards by Data App
Retrieve available dashboards in your data app
Embed a Pre-built Dashboard/Metric
Set up embed configurations for your data app
Guest Token API
Generate secure tokens for embedded access
⌘I

