> ## 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.

# List All Embeds

> Fetch a list of all embeds created by the authenticated data app.

Get a comprehensive list of all embed configurations created by your data app, including both dashboard and metric embeds with their associated metadata.

<Warning>
  **Endpoint Migration Notice:** We're transitioning to kebab-case endpoints. The new endpoint is `/api/v2/data-app/embeds`. The old endpoint `/api/v2/dataApp/embeds` will be deprecated soon. Please update your integrations to use the new endpoint format.
</Warning>

<Note>
  This endpoint returns all embeds you have access to within the authenticated data app. The response includes embed IDs, types, and associated dashboard/metric information.
</Note>

## Endpoint Formats

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

    **Use this endpoint** for all new integrations. This is the recommended endpoint format.
  </Tab>

  <Tab title="Legacy Endpoint (Deprecated Soon)">
    ```
    POST https://api.usedatabrain.com/api/v2/dataApp/embed/list
    Content-Type: application/json

    {
      "isPagination": true,
      "pageNumber": 1
    }
    ```

    This endpoint still works but will be deprecated. Uses POST method with JSON body.
  </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).

<Panel>
  <RequestExample>
    ```bash Authentication theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```
  </RequestExample>
</Panel>

## 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>

## Query Parameters

<ParamField query="isPagination" type="string">
  Whether to paginate results. 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">
  Page number to retrieve (1-based). Only used when isPagination is `"true"`. Must be a numeric string (e.g., `"1"`, `"2"`).
</ParamField>

<ParamField query="clientId" type="string">
  Optional client ID to filter embeds. When provided, only returns dashboard embeds where the dashboard was created by the specified client.
</ParamField>

## Response

<ResponseField name="data" type="array">
  Array of embed objects with their configuration details.
</ResponseField>

<ResponseField name="data.embedId" type="string">
  Unique identifier for the embed configuration.
</ResponseField>

<ResponseField name="data.embedType" type="string">
  Type of embed: "dashboard" or "metric".
</ResponseField>

<ResponseField name="data.name" type="string">
  The human-readable name of the embed configuration. This is the name set when creating or renaming the embed configuration.
</ResponseField>

<ResponseField name="data.externalDashboard" type="object | null">
  Dashboard information (present when embedType is "dashboard", null otherwise).

  <ResponseField name="data.externalDashboard.externalDashboardId" type="string">
    Unique identifier for the external dashboard.
  </ResponseField>

  <ResponseField name="data.externalDashboard.metadata" type="object">
    Dashboard metadata information.
  </ResponseField>

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

<ResponseField name="data.externalMetric" type="object | null">
  Metric information (present when embedType is "metric", null otherwise).

  <ResponseField name="data.externalMetric.metricId" type="string">
    Unique identifier for the external metric.
  </ResponseField>

  <ResponseField name="data.externalMetric.name" type="string">
    Name of the metric.
  </ResponseField>
</ResponseField>

<ResponseField name="data.embedMetadata" type="object">
  Consolidated metadata object containing key embed information for easy access.

  <ResponseField name="data.embedMetadata.embedId" type="string">
    Unique identifier for the embed configuration.
  </ResponseField>

  <ResponseField name="data.embedMetadata.name" type="string">
    The human-readable name of the embed configuration.
  </ResponseField>

  <ResponseField name="data.embedMetadata.embedType" type="string">
    Type of embed: "dashboard" or "metric".
  </ResponseField>

  <ResponseField name="data.embedMetadata.dataAppName" type="string">
    Name of the data app associated with this embed.
  </ResponseField>

  <ResponseField name="data.embedMetadata.metricId" type="string | null">
    Unique identifier for the metric (present when embedType is "metric", null otherwise).
  </ResponseField>

  <ResponseField name="data.embedMetadata.dashboardId" type="string | null">
    Unique identifier for the dashboard (present when embedType is "dashboard", null otherwise).
  </ResponseField>

  <ResponseField name="data.embedMetadata.createdAt" type="string">
    ISO 8601 formatted timestamp indicating when the embed configuration was created.
  </ResponseField>

  <ResponseField name="data.embedMetadata.updatedAt" type="string">
    ISO 8601 formatted timestamp indicating when the embed configuration was last updated.
  </ResponseField>
</ResponseField>

<ResponseField name="error" type="null">
  Error field, null when successful. Not included in successful responses.
</ResponseField>

## Examples

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

    ```javascript Node.js icon="fa-brands fa-node-js" theme={"dark"}
    const response = await fetch('https://api.usedatabrain.com/api/v2/data-app/embeds?isPagination=true&pageNumber=1', {
      method: 'GET',
      headers: {
        'Authorization': 'Bearer dbn_live_abc123...'
      }
    });

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

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

    url = "https://api.usedatabrain.com/api/v2/data-app/embeds"
    headers = {
        "Authorization": "Bearer dbn_live_abc123..."
    }
    params = {
        "isPagination": "true",
        "pageNumber": "1"
    }

    response = requests.get(url, headers=headers, params=params)
    data = response.json()
    print(f"Found embeds: {len(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/embeds')
    params = { isPagination: 'true', pageNumber: '1' }
    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 "Found embeds: #{data['data'].length}"
    ```

    ```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;

    public class DataBrainEmbedAPI {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            
            String url = "https://api.usedatabrain.com/api/v2/data-app/embeds" +
                "?isPagination=true&pageNumber=1";
            
            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 EmbedListResponse struct {
        Data  []interface{} `json:"data"`
        Error interface{}   `json:"error"`
    }

    func main() {
        baseURL := "https://api.usedatabrain.com/api/v2/data-app/embeds"
        params := url.Values{}
        params.Add("isPagination", "true")
        params.Add("pageNumber", "1")
        
        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 embedResp EmbedListResponse
        json.NewDecoder(resp.Body).Decode(&embedResp)
        
        fmt.Printf("Found embeds: %d\n", len(embedResp.Data))
    }
    ```

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

    $url = 'https://api.usedatabrain.com/api/v2/data-app/embeds?' . $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 "Found embeds: " . count($response['data']);
    ?>
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success Response theme={"dark"}
    {
      "data": [
        {
          "embedId": "dashboard-123",
          "embedType": "dashboard",
          "name": "Sales Dashboard Embed",
          "externalDashboard": {
            "externalDashboardId": "dashboard-uuid-456",
            "metadata": {
              "createdAt": "2024-01-15T10:30:00Z",
              "updatedAt": "2024-01-20T14:45:00Z"
            },
            "name": "Sales Analytics Dashboard"
          },
          "externalMetric": null,
          "embedMetadata": {
            "embedId": "dashboard-123",
            "name": "Sales Dashboard Embed",
            "embedType": "dashboard",
            "dataAppName": "Production Data App",
            "metricId": null,
            "dashboardId": "dashboard-uuid-456",
            "createdAt": "2024-01-15T10:30:00Z",
            "updatedAt": "2024-01-20T14:45:00Z"
          }
        },
        {
          "embedId": "metric-456",
          "embedType": "metric",
          "name": "Revenue Metric Embed",
          "externalDashboard": null,
          "externalMetric": {
            "metricId": "metric-uuid-789",
            "name": "Monthly Revenue"
          },
          "embedMetadata": {
            "embedId": "metric-456",
            "name": "Revenue Metric Embed",
            "embedType": "metric",
            "dataAppName": "Production Data App",
            "metricId": "metric-uuid-789",
            "dashboardId": null,
            "createdAt": "2024-01-16T08:15:00Z",
            "updatedAt": "2024-01-18T12:30:00Z"
          }
        }
      ],
      "error": null
    }
    ```

    ```json Error Response (400) theme={"dark"}
    {
      "error": {
        "code": "INVALID_DATA_APP_API_KEY",
        "message": "invalid or expired API KEY, data app not found"
      }
    }
    ```
  </ResponseExample>
</Panel>

## Error Codes

| Error Code                 | HTTP Status | Description                 |
| -------------------------- | ----------- | --------------------------- |
| `INVALID_DATA_APP_API_KEY` | 400         | Missing or invalid data app |
| `INTERNAL_SERVER_ERROR`    | 500         | Server error occurred       |

## 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 embed configurations">
    Get all your embed configurations:

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

    Note: You can add query parameters for pagination or filtering if needed.
  </Step>

  <Step title="Use pagination for many embeds">
    If you have many embed configurations, use pagination with query parameters:

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

  <Step title="Manage your embeds">
    Use the embed information to manage your configurations:

    ```javascript theme={"dark"}
    const embeds = await listEmbeds();
    embeds.data.forEach(embed => {
      console.log(`Embed ID: ${embed.embedId}`);
      console.log(`Embed Name: ${embed.name}`);
      console.log(`Type: ${embed.embedType}`);
      
      // Access timestamps and IDs from embedMetadata
      console.log(`Created: ${embed.embedMetadata.createdAt}`);
      console.log(`Updated: ${embed.embedMetadata.updatedAt}`);
      console.log(`Data App: ${embed.embedMetadata.dataAppName}`);
      
      if (embed.embedType === 'dashboard' && embed.externalDashboard) {
        console.log(`Dashboard ID: ${embed.externalDashboard.externalDashboardId}`);
        console.log(`Dashboard: ${embed.externalDashboard.name}`);
        console.log(`Dashboard ID (from metadata): ${embed.embedMetadata.dashboardId}`);
      } else if (embed.embedType === 'metric' && embed.externalMetric) {
        console.log(`Metric ID: ${embed.externalMetric.metricId}`);
        console.log(`Metric: ${embed.externalMetric.name}`);
        console.log(`Metric ID (from metadata): ${embed.embedMetadata.metricId}`);
      }
    });
    ```
  </Step>
</Steps>

## Next Steps

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

  <Card title="Update an Embed" href="/developer-docs/helpers/api-reference/update-embed">
    Modify existing embed access settings
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Delete an Embed" href="/developer-docs/helpers/api-reference/delete-embed">
    Remove embed configurations you no longer need
  </Card>

  <Card title="Query Metrics API" href="/developer-docs/helpers/api-reference/query-metric-api">
    Query data from your embedded metrics
  </Card>
</CardGroup>