List Schedule Reports by Embed

curl --request GET \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds/reports \
  --header 'Authorization: Bearer dbn_live_...'

{
  "data": [
    {
      "data.id": "<string>",
      "data.subject": "<string>",
      "data.scheduleEmailReportCharts": [
        {
          "data.scheduleEmailReportCharts[].externalMetric.metricId": "<string>"
        }
      ],
      "data.timeConfigurations": {},
      "data.createdAt": "<string>",
      "data.updatedAt": "<string>",
      "data.clientId": "<string>",
      "data.embedId": "<string>",
      "data.createdByIdentifier": {}
    }
  ],
  "error": {
    "error.code": "<string>",
    "error.message": "<string>"
  }
}

GET

api

data-app

embeds

reports

curl --request GET \
  --url https://api.usedatabrain.com/api/v2/data-app/embeds/reports \
  --header 'Authorization: Bearer dbn_live_...'

{
  "data": [
    {
      "data.id": "<string>",
      "data.subject": "<string>",
      "data.scheduleEmailReportCharts": [
        {
          "data.scheduleEmailReportCharts[].externalMetric.metricId": "<string>"
        }
      ],
      "data.timeConfigurations": {},
      "data.createdAt": "<string>",
      "data.updatedAt": "<string>",
      "data.clientId": "<string>",
      "data.embedId": "<string>",
      "data.createdByIdentifier": {}
    }
  ],
  "error": {
    "error.code": "<string>",
    "error.message": "<string>"
  }
}

Get a list of scheduled email reports associated with a specific embed configuration. This endpoint allows you to retrieve all scheduled reports for an embed, with optional filtering by client ID or user identifier, and supports pagination for large result sets.

This endpoint returns scheduled email reports that have been configured for the specified embed. Reports are filtered based on the embed’s data app and can be further filtered by client ID or user identifier.

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 for details. Finding your API token: For detailed instructions, see the API Token guide.

Headers

string

required

Bearer token for API authentication. Use your API key from the data app.

Authorization: Bearer dbn_live_abc123...

Query Parameters

string

required

The embed configuration ID to fetch scheduled reports for. This identifies which embedded dashboard’s scheduled reports you want to retrieve.

Show Finding embed IDs

Created when you configure an embed via the Create Embed API
Retrieved via the List Embeds API
Available in your DataBrain dashboard embed settings

string

Optional client identifier for filtering reports. When provided, only returns scheduled reports associated with the specified client.

Show Client filtering behavior

When clientId is provided: Returns only reports configured for that specific client
When omitted: Returns all scheduled reports for the embed (across all clients)
Useful for multi-tenant applications where each client has their own scheduled reports

string

Enable pagination to limit the number of results returned. Pass "true" to enable pagination with a limit of 10 reports per page.Note: Query parameters are passed as strings. Use "true" or "false".

string

Page number for pagination (1-based). Only used when isPagination is "true". Must be a numeric string (e.g., "1", "2").Default: If pagination is enabled and pageNumber is not provided, defaults to page 1.

string

Filter reports by the user identifier who created them. When provided, only returns scheduled reports created by the specified user.

Show User filtering behavior

When userIdentifier is provided: Returns only reports where createdByIdentifier matches
When omitted: Returns all scheduled reports for the embed (regardless of creator)
Useful for showing “My Scheduled Reports” views in your application

Response

array

Array of scheduled email report objects for the specified embed.

string

Unique identifier for the scheduled email report.

string

The subject line of the scheduled email report.

array

Array of charts/metrics included in this scheduled report.

string

The unique identifier of the metric included in the report.

object

Configuration object defining when and how often the report is scheduled to be sent.

Show Time configuration structure

Contains scheduling details such as frequency (daily, weekly, monthly), time of day, timezone, and other scheduling parameters.

string

ISO 8601 timestamp indicating when the scheduled report was created.

string

ISO 8601 timestamp indicating when the scheduled report was last updated.

string

The client identifier associated with this scheduled report. This is extracted from the guest token used when creating the report.

string

The embed configuration ID this scheduled report is associated with.

string | null

The identifier of the user who created this scheduled report, or null if not specified.

Non-null value: Indicates a user-created scheduled report with the creator’s identifier
null: Indicates a system-created or admin-created scheduled report

object

Error object returned only when the request fails. Not present in successful responses.

Show Error structure

string

Machine-readable error code for programmatic handling.

string

Human-readable error message explaining what went wrong.

Examples

HTTP Status Code Summary

Status Code	Description
`200`	OK - Scheduled reports retrieved successfully
`400`	Bad Request - Invalid request parameters, missing required fields, invalid API key, or embed ID not found
`500`	Internal Server Error - Server error occurred while processing the request

Possible Errors

Error Code	HTTP Status	Description
`INVALID_DATA_APP_API_KEY`	400	Invalid or expired API key, or data app not found
`INVALID_EMBED_ID`	400	Embed ID not found for the given data app
`INVALID_REQUEST_BODY`	400	Missing or invalid required parameters (e.g., embedId is required)
`INTERNAL_SERVER_ERROR`	500	An unexpected error occurred on the server

Filtering and Pagination

Client Filtering

When clientId is provided, the API returns only scheduled reports associated with that specific client:

// Get reports for a specific client
const clientReports = await fetch(`/api/v2/data-app/embeds/reports?embedId=embed_123&clientId=client_A`);

// Get all reports for the embed (across all clients)
const allReports = await fetch(`/api/v2/data-app/embeds/reports?embedId=embed_123`);

User Filtering

When userIdentifier is provided, the API returns only scheduled reports created by that user:

// Get reports created by a specific user
const userReports = await fetch(`/api/v2/data-app/embeds/reports?embedId=embed_123&userIdentifier=user_abc`);

// Get all reports (regardless of creator)
const allReports = await fetch(`/api/v2/data-app/embeds/reports?embedId=embed_123`);

Combined Filtering

You can combine clientId and userIdentifier to filter reports by both client and creator:

// Get reports for a specific client created by a specific user
const filteredReports = await fetch(
  `/api/v2/data-app/embeds/reports?embedId=embed_123&clientId=client_A&userIdentifier=user_abc`
);

Pagination

When pagination is enabled, results are limited to 10 reports per page:

// Get first page (reports 1-10)
const page1 = await fetch(`/api/v2/data-app/embeds/reports?embedId=embed_123&isPagination=true&pageNumber=1`);

// Get second page (reports 11-20)
const page2 = await fetch(`/api/v2/data-app/embeds/reports?embedId=embed_123&isPagination=true&pageNumber=2`);

Use Cases

1. Display Scheduled Reports in Dashboard

Show all scheduled reports configured for an embed in your application’s settings page:

async function loadScheduledReports(embedId) {
  const response = await fetch(
    `https://api.usedatabrain.com/api/v2/data-app/embeds/reports?embedId=${embedId}`,
    {
      headers: {
        'Authorization': `Bearer ${apiToken}`
      }
    }
  );
  
  const { data } = await response.json();
  return data; // Display in UI
}

2. Client-Specific Report Management

Allow clients to view and manage only their own scheduled reports:

async function getClientReports(embedId, clientId) {
  const response = await fetch(
    `https://api.usedatabrain.com/api/v2/data-app/embeds/reports?embedId=${embedId}&clientId=${clientId}`,
    {
      headers: {
        'Authorization': `Bearer ${apiToken}`
      }
    }
  );
  
  const { data } = await response.json();
  return data;
}

3. User-Specific Report View

Show users only the reports they created:

async function getUserReports(embedId, userIdentifier) {
  const response = await fetch(
    `https://api.usedatabrain.com/api/v2/data-app/embeds/reports?embedId=${embedId}&userIdentifier=${userIdentifier}`,
    {
      headers: {
        'Authorization': `Bearer ${apiToken}`
      }
    }
  );
  
  const { data } = await response.json();
  return data;
}

Authentication

Datasource APIs

Datamart APIs

Semantic Layer APIs

Workspace APIs

Embeds

Data App APIs

Metric APIs

Self-Hosted APIs

List Schedule Reports by Embed

Authentication

Headers

Query Parameters

Response

Examples

HTTP Status Code Summary

Possible Errors

Client Filtering

User Filtering

Combined Filtering

Use Cases

1. Display Scheduled Reports in Dashboard

2. Client-Specific Report Management

3. User-Specific Report View

​Authentication

​Headers

​Query Parameters

​Response

​Examples

​HTTP Status Code Summary

​Possible Errors

​Filtering and Pagination

​Client Filtering

​User Filtering

​Combined Filtering

​Pagination

​Use Cases

​1. Display Scheduled Reports in Dashboard

​2. Client-Specific Report Management

​3. User-Specific Report View

Authentication

Headers

Query Parameters

Response

Examples

HTTP Status Code Summary

Possible Errors

Filtering and Pagination

Client Filtering

User Filtering

Combined Filtering

Pagination

Use Cases

1. Display Scheduled Reports in Dashboard

2. Client-Specific Report Management

3. User-Specific Report View