> ## 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 Schedule Reports by Embed > Retrieve scheduled email reports for a specific embed configuration, with support for pagination and filtering by client or user identifier. 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](/guides/datasources/create-a-data-app) for details. **Finding your API token:** For detailed instructions, see the [API Token guide](/developer-docs/helpers/api-token). ```bash Authentication theme={"dark"} curl --request GET \ --url https://api.usedatabrain.com/api/v2/data-app/embeds/reports \ --header 'Authorization: Bearer dbn_live_...' ``` ## Headers Bearer token for API authentication. Use your API key from the data app. ``` Authorization: Bearer dbn_live_abc123... ``` ## Query Parameters The embed configuration ID to fetch scheduled reports for. This identifies which embedded dashboard's scheduled reports you want to retrieve. * Created when you configure an embed via the [Create Embed API](/developer-docs/helpers/api-reference/create-embed) * Retrieved via the [List Embeds API](/developer-docs/helpers/api-reference/list-embed) * Available in your DataBrain dashboard embed settings Optional client identifier for filtering reports. When provided, only returns scheduled reports associated with the specified client. * 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 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"`. 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. Filter reports by the user identifier who created them. When provided, only returns scheduled reports created by the specified user. * 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 of scheduled email report objects for the specified embed. Unique identifier for the scheduled email report. The subject line of the scheduled email report. Array of charts/metrics included in this scheduled report. The unique identifier of the metric included in the report. Configuration object defining when and how often the report is scheduled to be sent. Contains scheduling details such as frequency (daily, weekly, monthly), time of day, timezone, and other scheduling parameters. ISO 8601 timestamp indicating when the scheduled report was created. ISO 8601 timestamp indicating when the scheduled report was last updated. The client identifier associated with this scheduled report. This is extracted from the guest token used when creating the report. The embed configuration ID this scheduled report is associated with. 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 returned only when the request fails. Not present in successful responses. Machine-readable error code for programmatic handling. Human-readable error message explaining what went wrong. ## Examples ```bash cURL theme={"dark"} 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...' ``` ```javascript Node.js theme={"dark"} const params = new URLSearchParams({ embedId: 'embed_abc123', clientId: 'client_xyz789', isPagination: 'true', pageNumber: '1' }); const response = await fetch(`https://api.usedatabrain.com/api/v2/data-app/embeds/reports?${params}`, { method: 'GET', headers: { 'Authorization': 'Bearer dbn_live_abc123...' } }); const data = await response.json(); console.log('Scheduled reports:', data.data); ``` ```python Python theme={"dark"} import requests url = "https://api.usedatabrain.com/api/v2/dataApp/embeds/reports" headers = { "Authorization": "Bearer dbn_live_abc123..." } params = { "embedId": "embed_abc123", "clientId": "client_xyz789", "isPagination": "true", "pageNumber": "1" } response = requests.get(url, headers=headers, params=params) data = response.json() print(f"Scheduled reports: {data['data']}") ``` ```ruby Ruby theme={"dark"} require 'net/http' require 'json' uri = URI('https://api.usedatabrain.com/api/v2/data-app/embeds/reports') params = { embedId: 'embed_abc123', clientId: 'client_xyz789', 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 "Scheduled reports: #{data['data']}" ``` ```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 DataBrainScheduleReportsAPI { public static void main(String[] args) throws Exception { HttpClient client = HttpClient.newHttpClient(); String url = "https://api.usedatabrain.com/api/v2/data-app/embeds/reports" + "?embedId=embed_abc123&clientId=client_xyz789&isPagination=true&pageNumber=1"; HttpRequest request = HttpRequest.newBuilder() .uri(URI.create(url)) .header("Authorization", "Bearer dbn_live_abc123...") .GET() .build(); HttpResponse 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" "net/url" ) type ScheduleReport struct { Subject string `json:"subject"` ScheduleEmailReportCharts []struct { ExternalMetric struct { MetricID string `json:"metricId"` } `json:"externalMetric"` } `json:"scheduleEmailReportCharts"` TimeConfigurations interface{} `json:"timeConfigurations"` CreatedAt string `json:"createdAt"` UpdatedAt string `json:"updatedAt"` ClientID string `json:"clientId"` EmbedID string `json:"embedId"` CreatedByIdentifier *string `json:"createdByIdentifier"` } type ScheduleReportResponse struct { Data []ScheduleReport `json:"data"` Error interface{} `json:"error"` } func main() { baseURL := "https://api.usedatabrain.com/api/v2/data-app/embeds/reports" params := url.Values{} params.Add("embedId", "embed_abc123") params.Add("clientId", "client_xyz789") params.Add("isPagination", "true") params.Add("pageNumber", "1") fullURL := fmt.Sprintf("%s?%s", baseURL, params.Encode()) req, _ := http.NewRequest("GET", fullURL, 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 reportResp ScheduleReportResponse json.NewDecoder(resp.Body).Decode(&reportResp) fmt.Printf("Scheduled reports: %+v\n", reportResp.Data) } ``` ```php PHP theme={"dark"} 'embed_abc123', 'clientId' => 'client_xyz789', 'isPagination' => 'true', 'pageNumber' => '1' ]); $url = 'https://api.usedatabrain.com/api/v2/data-app/embeds/reports?' . $params; $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 "Scheduled reports: " . print_r($response['data'], true); ?> ``` ```json Success Response theme={"dark"} { "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 } ] } ``` ```json Empty Results Response theme={"dark"} { "data": [] } ``` ```json Error Response (400) theme={"dark"} { "error": { "code": "INVALID_DATA_APP_API_KEY", "message": "invalid or expired API KEY, data app not found" } } ``` ```json Error Response (400) theme={"dark"} { "error": { "code": "INVALID_EMBED_ID", "message": "invalid embed id, embed id not found for given data app" } } ``` ```json Error Response (400) theme={"dark"} { "error": { "code": "INVALID_REQUEST_BODY", "message": "\"embedId\" is required" } } ``` ## 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: ```javascript theme={"dark"} // 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: ```javascript theme={"dark"} // 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: ```javascript theme={"dark"} // 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: ```javascript theme={"dark"} // 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: ```javascript theme={"dark"} 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: ```javascript theme={"dark"} 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: ```javascript theme={"dark"} 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; } ```