Skip to main content
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds/reports?embedId=embed_abc123&clientId=client_xyz789&isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "id": "report-1",
      "subject": "Daily Sales Report",
      "scheduleEmailReportCharts": [
        {
          "externalMetric": {
            "metricId": "metric_revenue_123"
          }
        },
        {
          "externalMetric": {
            "metricId": "metric_orders_456"
          }
        }
      ],
      "timeConfigurations": {
        "frequency": "daily",
        "time": "09:00",
        "timezone": "UTC"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z",
      "clientId": "client_xyz789",
      "embedId": "embed_abc123",
      "createdByIdentifier": "user_abc123"
    },
    {
      "id": "report-2",
      "subject": "Weekly Summary Report",
      "scheduleEmailReportCharts": [
        {
          "externalMetric": {
            "metricId": "metric_users_789"
          }
        }
      ],
      "timeConfigurations": {
        "frequency": "weekly",
        "day": "monday",
        "time": "08:00",
        "timezone": "UTC"
      },
      "createdAt": "2024-01-10T08:15:00Z",
      "updatedAt": "2024-01-10T08:15:00Z",
      "clientId": "client_xyz789",
      "embedId": "embed_abc123",
      "createdByIdentifier": null
    }
  ]
}
GET
https://api.usedatabrain.com
/
api
/
v2
/
data-app
/
embeds
/
reports
curl --request GET \
  --url 'https://api.usedatabrain.com/api/v2/data-app/embeds/reports?embedId=embed_abc123&clientId=client_xyz789&isPagination=true&pageNumber=1' \
  --header 'Authorization: Bearer dbn_live_abc123...'

{
  "data": [
    {
      "id": "report-1",
      "subject": "Daily Sales Report",
      "scheduleEmailReportCharts": [
        {
          "externalMetric": {
            "metricId": "metric_revenue_123"
          }
        },
        {
          "externalMetric": {
            "metricId": "metric_orders_456"
          }
        }
      ],
      "timeConfigurations": {
        "frequency": "daily",
        "time": "09:00",
        "timezone": "UTC"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-20T14:22:00Z",
      "clientId": "client_xyz789",
      "embedId": "embed_abc123",
      "createdByIdentifier": "user_abc123"
    },
    {
      "id": "report-2",
      "subject": "Weekly Summary Report",
      "scheduleEmailReportCharts": [
        {
          "externalMetric": {
            "metricId": "metric_users_789"
          }
        }
      ],
      "timeConfigurations": {
        "frequency": "weekly",
        "day": "monday",
        "time": "08:00",
        "timezone": "UTC"
      },
      "createdAt": "2024-01-10T08:15:00Z",
      "updatedAt": "2024-01-10T08:15:00Z",
      "clientId": "client_xyz789",
      "embedId": "embed_abc123",
      "createdByIdentifier": null
    }
  ]
}
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

​
Authorization
string
required
Bearer token for API authentication. Use your API key from the data app.
Authorization: Bearer dbn_live_abc123...

​
Query Parameters

​
embedId
string
required
The embed configuration ID to fetch scheduled reports for. This identifies which embedded dashboard’s scheduled reports you want to retrieve.
​
clientId
string
Optional client identifier for filtering reports. When provided, only returns scheduled reports associated with the specified client.
​
isPagination
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".
​
pageNumber
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.
​
userIdentifier
string
Filter reports by the user identifier who created them. When provided, only returns scheduled reports created by the specified user.

​
Response

​
data
array
Array of scheduled email report objects for the specified embed.
​
data.id
string
Unique identifier for the scheduled email report.
​
data.subject
string
The subject line of the scheduled email report.
​
data.scheduleEmailReportCharts
array
Array of charts/metrics included in this scheduled report.
​
data.scheduleEmailReportCharts[].externalMetric.metricId
string
The unique identifier of the metric included in the report.
​
data.timeConfigurations
object
Configuration object defining when and how often the report is scheduled to be sent.
​
data.createdAt
string
ISO 8601 timestamp indicating when the scheduled report was created.
​
data.updatedAt
string
ISO 8601 timestamp indicating when the scheduled report was last updated.
​
data.clientId
string
The client identifier associated with this scheduled report. This is extracted from the guest token used when creating the report.
​
data.embedId
string
The embed configuration ID this scheduled report is associated with.
​
data.createdByIdentifier
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
​
error
object
Error object returned only when the request fails. Not present in successful responses.

​
Examples

​
HTTP Status Code Summary

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

​
Possible Errors

Error CodeHTTP StatusDescription
INVALID_DATA_APP_API_KEY400Invalid or expired API key, or data app not found
INVALID_EMBED_ID400Embed ID not found for the given data app
INVALID_REQUEST_BODY400Missing or invalid required parameters (e.g., embedId is required)
INTERNAL_SERVER_ERROR500An 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;
}