List Datamarts

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

GET /api/v2/data-app/datamarts

cURL

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

Success Response

{
  "data": [
    {
      "name": "sales-analytics",
      "datamartOrganization": {
        "tenancyLevel": "TABLE",
        "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)

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

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

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.

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.

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 (e.g., “TABLE”, “ROW”).

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

1. Get your API token

   For detailed instructions, see the Create Service Token guide.

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

3. 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...'
   
4. 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