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

> Retrieve a list of all datamarts in your data app with their configurations and access settings.

Get a comprehensive list of all datamarts in your data app, including their configurations, datasources, and access settings. Useful for managing and auditing your data organization.

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

<Note>
  This endpoint returns all datamarts you have access to within the authenticated data app. The response includes metadata and access permissions for each datamart.
</Note>

<Note>
  Use the **`expandDetails`** parameter when you only need names and organization metadata and want a smaller payload: when `expandDetails` is `false`, **`datamartTables`** and **`datamartRelationships`** are omitted from each item (see [Query Parameters](#query-parameters)).
</Note>

## Endpoint Formats

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

    **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/datamart/list
    Content-Type: application/json

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

    This endpoint still works but will be deprecated. **Content-Type:** `application/json`. The same **`getDatamartListSchema`** rules apply: optional **`isPagination`** (boolean), **`pageNumber`** (number), **`expandDetails`** (boolean).

    Send **`isPagination`** and **`pageNumber`** as JSON boolean and number — string values (for example `"true"`) usually fail Joi validation. For **`expandDetails`**, the route normalizes the body value before validation (booleans or string forms such as `"true"` / `"false"`); if **`expandDetails`** is omitted, **`getDatamartList`** defaults to expanded details, same as GET when the query parameter is omitted. Set it to `false` to omit **`datamartTables`** and **`datamartRelationships`** from each datamart.
  </Tab>
</Tabs>

## Authentication

This endpoint requires a service token in the Authorization header. Service tokens differ from data app API keys and provide organization-level permissions.

1. In **Settings** page, navigate to the **Service Tokens** section.
2. Click the **"Generate Token"** button to create a new service token if you don't have one already.

Use this token as the Bearer value in your Authorization header.

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

## Headers

<ParamField header="Authorization" type="string" required>
  Bearer token for API authentication. Use your service token.

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

## Query Parameters

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

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

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

<ParamField query="expandDetails" type="string">
  **GET only** (query string). Controls whether each datamart includes **`datamartTables`** (with **`datamartTableColumns`**) and **`datamartRelationships`** in the response.

  * If the **`expandDetails`** query parameter is **omitted**, the route passes **`expandDetails: true`** into **`getDatamartList`** (expanded).
  * If present, use the strings **`"true"`** or **`"false"`** (the server compares to `'true'`).

  When expanded details are **off** (`false`), each item still includes **`name`**, **`createdAt`**, **`updatedAt`**, **`datamartOrganization`**, and **`companyIntegration`**.

  **Legacy POST** accepts **`expandDetails`** in the JSON body; the route coerces it to a boolean before **`getDatamartListSchema`** runs (see the Legacy tab). Omit **`expandDetails`** to default to expanded details.

  **Note:** On GET, query parameters are strings — use `"true"` or `"false"`, not raw booleans.
</ParamField>

<Note>
  **Validation:** **`getDatamartListSchema`** allows optional **`isPagination`** (boolean), **`pageNumber`** (number), and **`expandDetails`** (boolean). On **GET** `/api/v2/data-app/datamarts`, query strings are mapped first: **`isPagination`** is `true` only when equal to **`"true"`**; **`pageNumber`** uses **`parseInt`** when present; **`expandDetails`** defaults to **`true`** when the query parameter is omitted, otherwise it is **`true`** only when the string equals **`"true"`**. On **POST** `/api/v2/dataApp/datamart/list`, **`isPagination`** and **`pageNumber`** are taken from the JSON body as-is; **`expandDetails`** is normalized from the body, then the same schema validates the combined payload inside **`getDatamartList`**.
</Note>

## Response

<Note>
  The **`datamartTables`** and **`datamartRelationships`** fields documented below are present **only when expanded details are enabled** (`expandDetails` not set to `false`). With `expandDetails=false`, rely on `name`, `createdAt`, `updatedAt`, `datamartOrganization`, and `companyIntegration` only.
</Note>

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

<ResponseField name="data.name" type="string">
  The name of the datamart.
</ResponseField>

<ResponseField name="data.datamartOrganization" type="object">
  Organization settings for the datamart.

  <ResponseField name="data.datamartOrganization.tenancyLevel" type="string">
    The tenancy level (`TABLE`, `DATABASE`, or `MULTI_DATABASE`).
  </ResponseField>

  <ResponseField name="data.datamartOrganization.schemaName" type="string">
    Schema name for the organization table.
  </ResponseField>

  <ResponseField name="data.datamartOrganization.tableName" type="string">
    Table name for the organization.
  </ResponseField>

  <ResponseField name="data.datamartOrganization.clientColumnType" type="string">
    Type of the client column.
  </ResponseField>

  <ResponseField name="data.datamartOrganization.primaryDatabase" type="string | null">
    Primary database name for `DATABASE` or `MULTI_DATABASE` tenancy. `null` when not set or when tenancy level is `TABLE`.
  </ResponseField>

  <ResponseField name="data.datamartOrganization.tableClientNameColumn" type="string">
    Column name for client identification.
  </ResponseField>

  <ResponseField name="data.datamartOrganization.tablePrimaryKeyColumn" type="string">
    Primary key column name.
  </ResponseField>
</ResponseField>

<ResponseField name="data.companyIntegration" type="object">
  Integration details for the datamart.

  <ResponseField name="data.companyIntegration.name" type="string">
    Name of the datasource integration.
  </ResponseField>
</ResponseField>

<ResponseField name="data.datamartTables" type="array">
  Array of tables included in the datamart.

  <ResponseField name="data.datamartTables.schemaName" type="string">
    Schema name of the table.
  </ResponseField>

  <ResponseField name="data.datamartTables.tableName" type="string">
    Name of the table.
  </ResponseField>

  <ResponseField name="data.datamartTables.label" type="string">
    Label for the table providing a human-readable display name. Empty string when not set.
  </ResponseField>

  <ResponseField name="data.datamartTables.clientColumn" type="string | null">
    Client/tenant column configured for this table. `null` when not set.
  </ResponseField>

  <ResponseField name="data.datamartTables.isHide" type="boolean">
    Indicates whether the table is hidden in the datamart UI. Defaults to `false`.
  </ResponseField>

  <ResponseField name="data.datamartTables.datamartTableColumns" type="array">
    Array of columns in the table.

    <ResponseField name="data.datamartTables.datamartTableColumns.columnName" type="string">
      Name of the column.
    </ResponseField>

    <ResponseField name="data.datamartTables.datamartTableColumns.datatype" type="string">
      Data type of the column.
    </ResponseField>

    <ResponseField name="data.datamartTables.datamartTableColumns.alias" type="string">
      Alias for the column.
    </ResponseField>

    <ResponseField name="data.datamartTables.datamartTableColumns.label" type="string">
      Label for the column providing better readability.
    </ResponseField>

    <ResponseField name="data.datamartTables.datamartTableColumns.isHide" type="boolean">
      Indicates whether the column is hidden in the datamart UI. Defaults to `false`.
    </ResponseField>

    <ResponseField name="data.datamartTables.datamartTableColumns.isCustomColumn" type="boolean">
      Indicates whether this is a custom/calculated column defined by a SQL expression. `true` when the column was created with `isCustomColumn: true`.
    </ResponseField>

    <ResponseField name="data.datamartTables.datamartTableColumns.sql" type="string">
      The SQL expression for custom columns. Empty string when `isCustomColumn` is `false`.
    </ResponseField>

    <ResponseField name="data.datamartTables.datamartTableColumns.isApplyTimezone" type="boolean">
      Indicates whether timezone conversion is enabled for this column. When `true`, datetime values are converted at query time using the timezone specified in `params.timezone` of the guest token. Defaults to `false`.
    </ResponseField>
  </ResponseField>
</ResponseField>

<ResponseField name="data.datamartRelationships" type="array">
  Array of relationships defined between tables in the datamart. Can be an empty array if no relationships are configured.

  <ResponseField name="data.datamartRelationships.parentTableName" type="string">
    Name of the parent table in the relationship.
  </ResponseField>

  <ResponseField name="data.datamartRelationships.parentColumnName" type="string">
    Column name in the parent table that participates in the relationship.
  </ResponseField>

  <ResponseField name="data.datamartRelationships.childTableName" type="string">
    Name of the child table in the relationship.
  </ResponseField>

  <ResponseField name="data.datamartRelationships.childColumnName" type="string">
    Column name in the child table that participates in the relationship.
  </ResponseField>

  <ResponseField name="data.datamartRelationships.relationshipName" type="string">
    Descriptive name for the relationship.
  </ResponseField>

  <ResponseField name="data.datamartRelationships.cardinality" type="string | null">
    The cardinality of the relationship. Can be: `ManyToMany`, `ManyToOne`, `OneToMany`, `OneToOne`, or `null` if not specified.
  </ResponseField>

  <ResponseField name="data.datamartRelationships.join" type="string | null">
    The type of SQL join used. Can be: `INNER JOIN`, `LEFT JOIN`, `RIGHT JOIN`, `FULL JOIN`, or `null` if not specified.
  </ResponseField>
</ResponseField>

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

## Examples

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

    ```bash cURL - List without expanded tables & relationships theme={"dark"}
    curl --request GET \
      --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?expandDetails=false&isPagination=true&pageNumber=1' \
      --header 'Authorization: Bearer dbn_live_abc123...'
    ```

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

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

    ```python Python theme={"dark"}
    import requests

    url = "https://api.usedatabrain.com/api/v2/data-app/datamarts"
    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 datamarts: {len(data['data'])}")
    ```

    ```ruby Ruby theme={"dark"}
    require 'net/http'
    require 'json'

    uri = URI('https://api.usedatabrain.com/api/v2/data-app/datamarts')
    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 datamarts: #{data['data'].length}"
    ```

    ```java Java theme={"dark"}
    import java.net.http.HttpClient;
    import java.net.http.HttpRequest;
    import java.net.http.HttpResponse;
    import java.net.URI;

    public class DataBrainDatamartAPI {
        public static void main(String[] args) throws Exception {
            HttpClient client = HttpClient.newHttpClient();
            
            String url = "https://api.usedatabrain.com/api/v2/data-app/datamarts?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 theme={"dark"}
    package main

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

    type DatamartListResponse struct {
        Data []interface{} `json:"data"`
    }

    func main() {
        url := "https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1"
        
        req, _ := http.NewRequest("GET", url, 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 datamartResp DatamartListResponse
        json.NewDecoder(resp.Body).Decode(&datamartResp)
        
        fmt.Printf("Found datamarts: %d\n", len(datamartResp.Data))
    }
    ```

    ```php PHP theme={"dark"}
    <?php
    $url = 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1';

    $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 datamarts: " . count($response['data']);
    ?>
    ```
  </RequestExample>

  <ResponseExample>
    ```json Success Response theme={"dark"}
    {
      "data": [
        {
          "name": "sales-analytics",
          "datamartOrganization": {
            "tenancyLevel": "TABLE",
            "primaryDatabase": null,
            "schemaName": "public",
            "tableName": "organizations",
            "clientColumnType": "STRING",
            "tableClientNameColumn": "name",
            "tablePrimaryKeyColumn": "id"
          },
          "companyIntegration": {
            "name": "postgres-prod"
          },
          "datamartTables": [
            {
              "schemaName": "public",
              "tableName": "customers",
              "label": "Customer Records",
              "clientColumn": "id",
              "isHide": false,
              "datamartTableColumns": [
                {
                  "columnName": "id",
                  "datatype": "integer",
                  "alias": "customer_id",
                  "label": "Customer ID",
                  "isHide": false,
                  "isCustomColumn": false,
                  "sql": "",
                  "isApplyTimezone": false
                },
                {
                  "columnName": "name",
                  "datatype": "varchar",
                  "alias": "customer_name",
                  "label": "Customer Name",
                  "isHide": false,
                  "isCustomColumn": false,
                  "sql": "",
                  "isApplyTimezone": false
                },
                {
                  "columnName": "created_at",
                  "datatype": "timestamp",
                  "alias": "created_at",
                  "label": "Created At",
                  "isHide": false,
                  "isCustomColumn": false,
                  "sql": "",
                  "isApplyTimezone": true
                }
              ]
            }
              ]
            }
          ],
          "datamartRelationships": [
            {
              "parentTableName": "orders",
              "parentColumnName": "customer_id",
              "childTableName": "customers",
              "childColumnName": "id",
              "relationshipName": "orders_to_customers",
              "cardinality": "ManyToOne",
              "join": "LEFT JOIN"
            }
          ]
        }
      ],
      "error": null
    }
    ```

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

## Error Codes

<ResponseField name="INVALID_DATA_APP_API_KEY" type="string">
  **Missing or invalid data app** - Check your API key and data app configuration
</ResponseField>

<ResponseField name="INTERNAL_SERVER_ERROR" type="string">
  **Unexpected failure** - Internal server error occurred
</ResponseField>

## HTTP Status Code Summary

| Status Code | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| 200         | **OK** - Request successful                                     |
| 400         | **Bad Request** - Invalid request parameters or missing API key |
| 401         | **Unauthorized** - Invalid or expired API token                 |
| 500         | **Internal Server Error** - Unexpected server error             |

## Possible Errors

| Code                         | Message                     | HTTP Status |
| ---------------------------- | --------------------------- | ----------- |
| INVALID\_DATA\_APP\_API\_KEY | Missing or invalid data app | 400         |
| INTERNAL\_SERVER\_ERROR      | Unexpected failure          | 500         |

## Usage Examples

### Basic Usage

```javascript theme={"dark"}
// Get all datamarts
const datamarts = await listDatamarts();
console.log(`Total datamarts: ${datamarts.data.length}`);
```

### With Pagination

```javascript theme={"dark"}
// Get first page of datamarts
const datamarts = await listDatamarts({
  isPagination: true,
  pageNumber: 1
});
console.log(`Page 1 datamarts: ${datamarts.data.length}`);
```

### Processing Results

```javascript theme={"dark"}
// Process each datamart
const datamarts = await listDatamarts();
datamarts.data.forEach(datamart => {
  console.log(`Datamart: ${datamart.name}`);
  console.log(`Tables: ${datamart.datamartTables.length}`);
  console.log(`Datasource: ${datamart.companyIntegration.name}`);
});
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Use Pagination" icon="list">
    Use pagination for data apps with many datamarts
  </Card>

  <Card title="Cache Results" icon="clock">
    Cache datamart lists to reduce API calls
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Error Handling" icon="shield">
    Always handle API errors gracefully
  </Card>

  <Card title="Monitor Usage" icon="chart-line">
    Monitor API usage and response times
  </Card>
</CardGroup>

## Quick Start Guide

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

  <Step title="List all datamarts">
    Make a simple request to see all your datamarts:

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

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

  <Step title="Use pagination for large lists">
    If you have many datamarts, enable pagination using query parameters:

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

  <Step title="Process the results">
    Use the datamart information for embed configurations:

    ```javascript theme={"dark"}
    const datamarts = await listDatamarts();
    datamarts.data.forEach(datamart => {
      console.log(`Datamart: ${datamart.name}`);
      console.log(`Tables: ${datamart.datamartTables.length}`);
    });
    ```
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create Datamart" href="/developer-docs/helpers/api-reference/create-datamart">
    Create new datamarts for your data app
  </Card>

  <Card title="Delete Datamart" href="/developer-docs/helpers/api-reference/delete-datamart">
    Remove datamarts you no longer need
  </Card>
</CardGroup>

<CardGroup cols={2}>
  <Card title="Embed a Pre-built Dashboard/Metric" href="/developer-docs/helpers/api-reference/create-embed">
    Create embeddable configurations for your datamarts
  </Card>

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