> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usedatabrain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Fetch Dashboards by Data App

> Retrieve a list of dashboards available in your data app with optional filtering and pagination.

Fetch all dashboards associated with your data app. This endpoint allows you to discover available dashboards for embedding or integration purposes, with support for filtering by dashboard names and pagination.

<Warning>
  **API Method Migration Notice:** We're transitioning from POST to GET for this endpoint. The new GET method is recommended for all new integrations. The POST method will be deprecated soon.
</Warning>

<Note>
  This endpoint returns dashboards that have been configured for your data app. Use the dashboard information to create embed configurations or for display purposes.
</Note>

## API Methods

<Tabs>
  <Tab title="GET (Recommended)">
    ```
    GET https://api.usedatabrain.com/api/v2/data-app/dashboards
    ```

    **Use this method** for all new integrations. This is the recommended approach with query parameters.
  </Tab>

  <Tab title="POST (Deprecated Soon)">
    ```
    POST https://api.usedatabrain.com/api/v2/data-app/dashboards
    ```

    This method still works but will be deprecated. Please migrate to the GET method.
  </Tab>
</Tabs>

## 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](/guides/datasources/create-a-data-app) for details.

**Finding your API token:** For detailed instructions, see the [API Token guide](/developer-docs/helpers/api-token).

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your API key from the data app.

  ```
  Authorization: Bearer dbn_live_abc123...
  ```
</ParamField>

<ParamField header="Content-Type" type="string">
  Required only for POST method. Must be set to `application/json`.

  ```
  Content-Type: application/json
  ```
</ParamField>

## Query Parameters

<ParamField query="isPagination" type="string" required>
  Enable pagination to limit the number of results returned. Pass `"true"` to enable pagination with a limit of 10 per page.

  **Note:** Query parameters are passed as strings. Use `"true"` or `"false"`.
</ParamField>

<ParamField query="pageNumber" type="string" required>
  Page number for pagination (1-based). Only used when isPagination is `"true"`. Must be a numeric string (e.g., `"1"`, `"2"`).
</ParamField>

<ParamField query="dashboardNames" type="string">
  Comma-separated list of dashboard names to filter by. Only dashboards with matching names will be returned.

  **Example:** `"Sales Dashboard,Marketing Analytics,Customer Insights"`
</ParamField>

## Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/dashboards?isPagination=true&pageNumber=1&dashboardNames=Sales%20Dashboard,Marketing%20Analytics' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const params = new URLSearchParams({
      isPagination: 'true',
      pageNumber: '1',
      dashboardNames: 'Sales Dashboard,Marketing Analytics'
    });

    const response = await fetch(`https://api.usedatabrain.com/api/v2/data-app/dashboards?${params}`, {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...'
      }
    });

    const data = await response.json();
    console.log('Dashboards:', data.data);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/dashboards"
    headers = {
        "Authorization": "Bearer dbn_live_abc123..."
    }
    params = {
        "isPagination": "true",
        "pageNumber": "1",
        "dashboardNames": "Sales Dashboard,Marketing Analytics"
    }

    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    print(f"Dashboards: {data['data']}")
    ```

    ```ruby Ruby icon="fa-solid fa-gem" theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/data-app/dashboards')
    params = {
      isPagination: 'true',
      pageNumber: '1',
      dashboardNames: 'Sales Dashboard,Marketing Analytics'
    }
    uri.query = URI.encode_www_form(params)

    http = Net::HTTP.new(uri.host, uri.port)
    http.use_ssl = true

    request = Net::HTTP::Get.new(uri)
    request['Authorization'] = 'Bearer dbn_live_abc123...'

    response = http.request(request)
    data = JSON.parse(response.body)
    puts "Dashboards: #{data['data']}"
    ```

    ```java Java icon="fa-brands fa-java" theme={"dark"}
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.net.URI;
    import java.net.URLEncoder;
    import java.nio.charset.StandardCharsets;

    public class DataBrainDashboardsAPI {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            
            String dashboardNames = URLEncoder.encode("Sales Dashboard,Marketing Analytics", StandardCharsets.UTF_8);
            String url = String.format(
                "https://api.usedatabrain.com/api/v2/data-app/dashboards?isPagination=true&pageNumber=1&dashboardNames=%s",
                dashboardNames
            );
            
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create(url))
                .header("Authorization", "Bearer dbn_live_abc123...")
                .GET()
                .build();
                
            HttpResponse<String> response = client.send(request, 
                HttpResponse.BodyHandlers.ofString());
                
            System.out.println("Response: " + response.body());
        }
    }
    ```

    ```go Go icon="fa-brands fa-golang" theme={"dark"}
    package main

    import (
        "encoding/json"
        "fmt"
        "net/http"
        "net/url"
    )

    type Dashboard struct {
        Name                string `json:"name"`
        ExternalDashboardID string `json:"externalDashboardId"`
        EmbedID             string `json:"embedId"`
    }

    type DashboardResponse struct {
        Data  []Dashboard   `json:"data"`
        Error interface{}   `json:"error"`
    }

    func main() {
        baseURL := "https://api.usedatabrain.com/api/v2/data-app/dashboards"
        params := url.Values{}
        params.Add("isPagination", "true")
        params.Add("pageNumber", "1")
        params.Add("dashboardNames", "Sales Dashboard,Marketing Analytics")
        
        fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode())
        
        req, _ := http.NewRequest("GET", fullURL, nil)
        req.Header.Set("Authorization", "Bearer dbn_live_abc123...")
        
        client := &http.Client{}
        resp, err := client.Do(req)
        if err != nil {
            panic(err)
        }
        defer resp.Body.Close()
        
        var dashboardResp DashboardResponse
        json.NewDecoder(resp.Body).Decode(&dashboardResp)
        
        fmt.Printf("Dashboards: %+v\n", dashboardResp.Data)
    }
    ```

    ```php PHP icon="fa-brands fa-php" theme={"dark"}
    <?php
    $params = http_build_query([
        'isPagination' => 'true',
        'pageNumber' => '1',
        'dashboardNames' => 'Sales Dashboard,Marketing Analytics'
    ]);

    $url = 'https://api.usedatabrain.com/api/v2/data-app/dashboards?' . $params;

    $options = [
        'http' => [
            'header' => 'Authorization: Bearer dbn_live_abc123...',
            'method' => 'GET'
        ]
    ];

    $context = stream_context_create($options);
    $result = file_get_contents($url, false, $context);
    $response = json_decode($result, true);

    echo "Dashboards: " . print_r($response['data'], true);
    ?>
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success Response theme={"dark"}
    {
      "data": [
        {
          "name": "Sales Dashboard",
          "externalDashboardId": "sales_dash_123",
          "embedId": "embed_abc123"
        },
        {
          "name": "Marketing Analytics",
          "externalDashboardId": "marketing_dash_456",
          "embedId": "embed_def456"
        }
      ]
    }
    ```

    ```json Empty Results Response theme={"dark"}
    {
      "data": []
    }
    ```

    ```json Error Response (401) theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_API_KEY",
        "message": "Invalid or missing Data App API Key"
      }
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_REQUEST_BODY",
        "message": "Required fields missing or wrong type"
      }
    }
    ```
  </ResponseExample>
</Panel>

## Legacy Endpoint Examples

<Note>
  The following examples use the deprecated POST method. These are provided for reference only. **Please use the GET method examples above for all new integrations.**
</Note>

## POST Method (Legacy - Being Deprecated)

### Request Body (POST)

<ParamField body="isPagination" type="boolean">
  Enable pagination to limit the number of results returned. When enabled, use `pageNumber` to navigate through pages.
</ParamField>

<ParamField body="pageNumber" type="number">
  Page number for pagination (1-based). Only used when `isPagination` is `true`. Each page returns up to 10 dashboards.
</ParamField>

<ParamField body="filters" type="object">
  Optional filters to narrow down the dashboard results.

  <ParamField body="filters.dashboardNames" type="array">
    Array of specific dashboard names to filter by. Only dashboards with matching names will be returned.

    ```json Example theme={"dark"}
    ["Sales Dashboard", "Marketing Analytics", "Customer Insights"]
    ```
  </ParamField>
</ParamField>

### POST Examples

<Panel>
  <RequestExample>
    ```bash cURL theme={"dark"}
    curl --request POST \
      --url https://api.usedatabrain.com/api/v2/data-app/dashboards \
      --header 'Authorization: Bearer dbn_live_abc123...' \
      --header 'Content-Type: application/json' \
      --data '{
        "isPagination": true,
        "pageNumber": 1,
        "filters": {
          "dashboardNames": ["Sales Dashboard", "Marketing Analytics"]
        }
      }'
    ```

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/dashboards', {
      method: 'POST',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        isPagination: true,
        pageNumber: 1,
        filters: {
          dashboardNames: ['Sales Dashboard', 'Marketing Analytics']
        }
      })
    });

    const data = await response.json();
    console.log('Dashboards:', data.data);
    ```

    ```python Python icon="fa-brands fa-python" theme={"dark"}
    import requests
    import json

    url = "https://api.usedatabrain.com/api/v2/data-app/dashboards"
    headers = {
        "Authorization": "Bearer dbn_live_abc123...",
        "Content-Type": "application/json"
    }
    payload = {
        "isPagination": True,
        "pageNumber": 1,
        "filters": {
            "dashboardNames": ["Sales Dashboard", "Marketing Analytics"]
        }
    }

    response = requests.post(url, headers=headers, data=json.dumps(payload))
    data = response.json()
    print(f"Dashboards: {data['data']}")
    ```

    ```ruby Ruby icon="fa-solid fa-gem" theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/data-app/dashboards')
    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 = {
      isPagination: true,
      pageNumber: 1,
      filters: {
        dashboardNames: ['Sales Dashboard', 'Marketing Analytics']
      }
    }.to_json

    response = http.request(request)
    data = JSON.parse(response.body)
    puts "Dashboards: #{data['data']}"
    ```

    ```java Java icon="fa-brands fa-java" theme={"dark"}
    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;
    import java.util.List;
    import java.util.Arrays;

    public class DataBrainDashboardsAPI {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            ObjectMapper mapper = new ObjectMapper();
            
            Map<String, Object> filters = new HashMap<>();
            filters.put("dashboardNames", Arrays.asList("Sales Dashboard", "Marketing Analytics"));
            
            Map<String, Object> requestBody = new HashMap<>();
            requestBody.put("isPagination", true);
            requestBody.put("pageNumber", 1);
            requestBody.put("filters", filters);
            
            String jsonBody = mapper.writeValueAsString(requestBody);
            
            HttpRequest request = HttpRequest.newBuilder()
                .uri(URI.create("https://api.usedatabrain.com/api/v2/data-app/dashboards"))
                .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());
        }
    }
    ```

    ```go Go icon="fa-brands fa-golang" theme={"dark"}
    package main

    import (
        "bytes"
        "encoding/json"
        "fmt"
        "net/http"
    )

    type DashboardFilters struct {
        DashboardNames []string `json:"dashboardNames"`
    }

    type DashboardRequest struct {
        IsPagination bool              `json:"isPagination"`
        PageNumber   int               `json:"pageNumber"`
        Filters      DashboardFilters  `json:"filters"`
    }

    type Dashboard struct {
        Name                  string `json:"name"`
        ExternalDashboardID   string `json:"externalDashboardId"`
        EmbedID              string `json:"embedId"`
    }

    type DashboardResponse struct {
        Data  []Dashboard   `json:"data"`
        Error interface{}   `json:"error"`
    }

    func main() {
        reqBody := DashboardRequest{
            IsPagination: true,
            PageNumber:   1,
            Filters: DashboardFilters{
                DashboardNames: []string{"Sales Dashboard", "Marketing Analytics"},
            },
        }
        
        jsonData, _ := json.Marshal(reqBody)
        
        req, _ := http.NewRequest("POST", 
            "https://api.usedatabrain.com/api/v2/data-app/dashboards", 
            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 dashboardResp DashboardResponse
        json.NewDecoder(resp.Body).Decode(&dashboardResp)
        
        fmt.Printf("Dashboards: %+v\n", dashboardResp.Data)
    }
    ```

    ```php PHP icon="fa-brands fa-php" theme={"dark"}
    <?php
    $url = 'https://api.usedatabrain.com/api/v2/data-app/dashboards';
    $data = [
        'isPagination' => true,
        'pageNumber' => 1,
        'filters' => [
            'dashboardNames' => ['Sales Dashboard', 'Marketing Analytics']
        ]
    ];

    $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 "Dashboards: " . print_r($response['data'], true);
    ?>
    ```
  </RequestExample>
</Panel>

## Response (Success 200)

<ResponseField name="data" type="array">
  Array of dashboard objects available in your data app.

  <ResponseField name="data.name" type="string">
    Display name of the dashboard.
  </ResponseField>

  <ResponseField name="data.externalDashboardId" type="string">
    Unique identifier for the dashboard that can be used in embed configurations.
  </ResponseField>

  <ResponseField name="data.embedId" type="string">
    Embed ID associated with this dashboard, if available.
  </ResponseField>
</ResponseField>

## Error Response

<ResponseField name="error" type="object">
  Error object returned only when the request fails. Not included in successful responses.

  <ResponseField name="error.code" type="string">
    Error code identifier.
  </ResponseField>

  <ResponseField name="error.message" type="string">
    Human-readable error message.
  </ResponseField>
</ResponseField>

## Error Codes

<ResponseField name="INVALID_DATA_APP_API_KEY" type="string">
  **Invalid or missing Data App API Key** - Check your API key and ensure it's valid for your data app
</ResponseField>

<ResponseField name="INVALID_REQUEST_BODY" type="string">
  **Invalid request parameters** - Verify that your request body contains valid field types
</ResponseField>

## HTTP Status Code Summary

| Status Code | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `200`       | **OK** - Dashboards retrieved successfully                      |
| `400`       | **Bad Request** - Invalid request parameters or missing API key |
| `401`       | **Unauthorized** - Invalid or missing API key                   |
| `429`       | **Too Many Requests** - Rate limit exceeded                     |
| `500`       | **Internal Server Error** - Server error occurred               |

## Possible Errors

| Error Code                 | HTTP Status | Description          |
| -------------------------- | ----------- | -------------------- |
| `INVALID_DATA_APP_API_KEY` | 401         | Invalid API key      |
| `INVALID_REQUEST_BODY`     | 400         | Invalid request body |
| `RATE_LIMIT_EXCEEDED`      | 429         | Too many requests    |
| `INTERNAL_SERVER_ERROR`    | 500         | Server error         |

## Pagination Guide

When using pagination:

1. **Enable pagination** by setting `isPagination` to `true` (GET) or `true` (POST)
2. **Start with page 1** using `pageNumber=1` (GET) or `pageNumber: 1` (POST)
3. **Each page returns up to 10 dashboards**
4. **Continue to next page** if you receive exactly 10 results
5. **Stop pagination** when you receive fewer than 10 results

### GET Method Pagination Example:

```
GET /api/v2/data-app/dashboards?isPagination=true&pageNumber=1
```

### POST Method Pagination Example:

```json theme={"dark"}
{
  "isPagination": true,
  "pageNumber": 1
}
```

## Filtering Options

### Dashboard Name Filtering

**GET Method:** Use comma-separated values in query parameter

```
?dashboardNames=Dashboard%201,Dashboard%202
```

**POST Method:** Use array in request body

```json theme={"dark"}
{
  "filters": {
    "dashboardNames": ["Dashboard 1", "Dashboard 2"]
  }
}
```

This is useful when you know the exact dashboard names you want to work with.

## Migration Guide: POST to GET

If you're currently using the POST method, here's how to migrate to GET:

### Before (POST):

```javascript theme={"dark"}
const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/dashboards', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer dbn_live_...',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    isPagination: true,
    pageNumber: 1,
    filters: {
      dashboardNames: ['Sales Dashboard']
    }
  })
});
```

### After (GET):

```javascript theme={"dark"}
const params = new URLSearchParams({
  isPagination: 'true',
  pageNumber: '1',
  dashboardNames: 'Sales Dashboard'
});

const response = await fetch(`https://api.usedatabrain.com/api/v2/data-app/dashboards?${params}`, {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer dbn_live_...'
  }
});
```

### Key Differences:

1. **Method**: POST → GET
2. **Parameters**: Request body → Query parameters
3. **Boolean values**: `true` → `"true"` (string in query params)
4. **Number values**: `1` → `"1"` (string in query params)
5. **Dashboard names**: Array `["name1", "name2"]` → Comma-separated string `"name1,name2"`
6. **Content-Type header**: Not needed for GET

## Quick Start Guide

<Steps>
  <Step title="Get your API token">
    For detailed instructions, see the [API Token guide](/developer-docs/helpers/api-token).
  </Step>

  <Step title="List all dashboards (GET - Recommended)">
    Get all dashboards available in your data app:

    ```bash theme={"dark"}
    curl --request GET \
      --url https://api.usedatabrain.com/api/v2/data-app/dashboards \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```
  </Step>

  <Step title="Filter by specific dashboard names">
    If you're looking for specific dashboards, use query parameters:

    ```bash theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/dashboards?dashboardNames=Sales%20Dashboard,Marketing%20Analytics' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```
  </Step>

  <Step title="Use dashboard information for embedding">
    Process the dashboard data to create embed configurations:

    ```javascript theme={"dark"}
    const dashboards = await fetchDataAppDashboards();

    dashboards.data.forEach(dashboard => {
      console.log(`Dashboard: ${dashboard.name}`);
      console.log(`External ID: ${dashboard.externalDashboardId}`);
      
      // Use the externalDashboardId to create embed configurations
      if (!dashboard.embedId) {
        console.log('This dashboard can be made embeddable');
      }
    });
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Embed a Pre-built Dashboard/Metric" href="/developer-docs/helpers/api-reference/create-embed">
    Use dashboard IDs to create embed configurations
  </Card>

  <Card title="Fetch Metrics by Embed" href="/developer-docs/helpers/api-reference/fetch-metrics-by-embed-and-client">
    Get metrics available for specific embedded dashboards
  </Card>

  <Card title="Query Metric Data" href="/developer-docs/helpers/api-reference/fetch-metric-data-by-dataapp">
    Query data from your dashboard metrics
  </Card>

  <Card title="Guest Token API" href="/developer-docs/helpers/api-reference/token">
    Generate secure tokens for embedded access
  </Card>
</CardGroup>