List Datamarts - Databrain

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "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
}

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "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
}

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "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
}

GET

api

data-app

datamarts

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "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
}

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.

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.

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

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

Endpoint Formats

New Endpoint (Recommended)
Legacy Endpoint (Deprecated Soon)

GET https://api.usedatabrain.com/api/v2/data-app/datamarts

Use this endpoint for all new integrations. This is the recommended endpoint format.

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.

Authentication

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

In Settings page, navigate to the Service Tokens section.
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.

Headers

Authorization

string

required

Bearer token for API authentication. Use your service token.

Authorization: Bearer dbn_live_abc123...

Query Parameters

isPagination

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

pageNumber

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").

expandDetails

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.

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.

Response

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.

data

array

Array of datamart objects with their configuration details.

data.name

string

The name of the datamart.

data.datamartOrganization

object

Organization settings for the datamart.

data.datamartOrganization.tenancyLevel

string

The tenancy level (TABLE, DATABASE, or MULTI_DATABASE).

data.datamartOrganization.schemaName

string

Schema name for the organization table.

data.datamartOrganization.tableName

string

Table name for the organization.

data.datamartOrganization.clientColumnType

string

Type of the client column.

data.datamartOrganization.primaryDatabase

string | null

Primary database name for DATABASE or MULTI_DATABASE tenancy. null when not set or when tenancy level is TABLE.

data.datamartOrganization.tableClientNameColumn

string

Column name for client identification.

data.datamartOrganization.tablePrimaryKeyColumn

string

Primary key column name.

data.companyIntegration

object

Integration details for the datamart.

data.companyIntegration.name

string

Name of the datasource integration.

data.datamartTables

array

Array of tables included in the datamart.

data.datamartTables.schemaName

string

Schema name of the table.

data.datamartTables.tableName

string

Name of the table.

data.datamartTables.label

string

Label for the table providing a human-readable display name. Empty string when not set.

data.datamartTables.clientColumn

string | null

Client/tenant column configured for this table. null when not set.

data.datamartTables.isHide

boolean

Indicates whether the table is hidden in the datamart UI. Defaults to false.

data.datamartTables.datamartTableColumns

array

Array of columns in the table.

data.datamartTables.datamartTableColumns.columnName

string

Name of the column.

data.datamartTables.datamartTableColumns.datatype

string

Data type of the column.

data.datamartTables.datamartTableColumns.alias

string

Alias for the column.

data.datamartTables.datamartTableColumns.label

string

Label for the column providing better readability.

data.datamartTables.datamartTableColumns.isHide

boolean

Indicates whether the column is hidden in the datamart UI. Defaults to false.

data.datamartTables.datamartTableColumns.isCustomColumn

boolean

Indicates whether this is a custom/calculated column defined by a SQL expression. true when the column was created with isCustomColumn: true.

data.datamartTables.datamartTableColumns.sql

string

The SQL expression for custom columns. Empty string when isCustomColumn is false.

data.datamartTables.datamartTableColumns.isApplyTimezone

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.

data.datamartRelationships

array

Array of relationships defined between tables in the datamart. Can be an empty array if no relationships are configured.

data.datamartRelationships.parentTableName

string

Name of the parent table in the relationship.

data.datamartRelationships.parentColumnName

string

Column name in the parent table that participates in the relationship.

data.datamartRelationships.childTableName

string

Name of the child table in the relationship.

data.datamartRelationships.childColumnName

string

Column name in the child table that participates in the relationship.

data.datamartRelationships.relationshipName

string

Descriptive name for the relationship.

data.datamartRelationships.cardinality

string | null

The cardinality of the relationship. Can be: ManyToMany, ManyToOne, OneToMany, OneToOne, or null if not specified.

data.datamartRelationships.join

string | null

The type of SQL join used. Can be: INNER JOIN, LEFT JOIN, RIGHT JOIN, FULL JOIN, or null if not specified.

error

null

Error field, null when successful.

Examples

Error Codes

INVALID_DATA_APP_API_KEY

string

Missing or invalid data app - Check your API key and data app configuration

INTERNAL_SERVER_ERROR

string

Unexpected failure - Internal server error occurred

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

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

With Pagination

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

Processing Results

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

Use Pagination

Use pagination for data apps with many datamarts

Cache Results

Cache datamart lists to reduce API calls

Error Handling

Always handle API errors gracefully

Monitor Usage

Monitor API usage and response times

Quick Start Guide

Get your API token

For detailed instructions, see the Create Service Token guide.

List all datamarts

Make a simple request to see all your datamarts:

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.

Use pagination for large lists

If you have many datamarts, enable pagination using query parameters:

curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/datamarts?isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

Process the results

Use the datamart information for embed configurations:

const datamarts = await listDatamarts();
datamarts.data.forEach(datamart => {
  console.log(`Datamart: ${datamart.name}`);
  console.log(`Tables: ${datamart.datamartTables.length}`);
});

Next Steps

Create Datamart

Create new datamarts for your data app

Delete Datamart

Remove datamarts you no longer need

Embed a Pre-built Dashboard/Metric

Create embeddable configurations for your datamarts

Guest Token API

Generate secure tokens for embedded access

Create Datamart

Update Datamart

​Endpoint Formats

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​Error Codes

​HTTP Status Code Summary

​Possible Errors

​Usage Examples

​Basic Usage

​With Pagination

​Processing Results

​Best Practices

Use Pagination

Cache Results

Error Handling

Monitor Usage

​Quick Start Guide

​Next Steps

Create Datamart

Delete Datamart

Embed a Pre-built Dashboard/Metric

Guest Token API

Endpoint Formats

Authentication

Headers

Query Parameters

Response

Examples

Error Codes

HTTP Status Code Summary

Possible Errors

Usage Examples

Basic Usage

With Pagination

Processing Results

Best Practices

Quick Start Guide

Next Steps