Skip to main content

Reports - Preview HTML

Endpoint​

/i/reports/preview

Overview​

Generates report output and returns preview as raw HTML.

Authentication​

Countly API supports three authentication methods:

  1. api_key=YOUR_API_KEY
  2. auth_token=YOUR_AUTH_TOKEN
  3. countly-token: YOUR_AUTH_TOKEN

Permissions​

Requires reports Read permission.

Request Parameters​

ParameterTypeRequiredDescription
api_keyStringConditionalRequired if auth_token is not provided.
auth_tokenStringConditionalRequired if api_key is not provided.
app_idStringYesApp ID used by permission validation.
argsString (JSON Object)YesMust include report _id.
args._idStringYesTarget report ID.

Configuration Impact​

SettingDefaultAffectsUser-visible impact
api.offline_modefalseReport enrichment during report generationWhen enabled, external news/universe enrichment is skipped, so preview content can differ from online mode.

Response​

Success Response​

Raw HTML response with headers:

Content-Type: text/html; charset=utf-8
Access-Control-Allow-Origin: *

<!DOCTYPE html>
<html>...</html>

Response Fields​

FieldTypeDescription
(response body)String (HTML)Full rendered report HTML payload.
Content-TypeHeadertext/html; charset=utf-8
Access-Control-Allow-OriginHeader*

Error Responses​

  • 200
{
  "result": "Not enough args"
}
  • 200
{
  "result": "Report not found"
}
  • 200
{
  "result": "No data to report"
}
  • 200
{
  "result": "Error while generating report"
}

Standard authentication/authorization errors from read validation can also be returned.

Behavior/Processing​

  • Parses args JSON before route execution.
  • Uses owner-scoped lookup for non-global-admin users.
  • Loads the target report and builds report HTML preview data.
  • For non-core report types, renders HTML from res.message.template and res.message.data via EJS.
  • Returns raw HTML response body (not wrapped JSON on success).

Database Collections​

CollectionUsed forData touched by this endpoint
countly.reportsReport sourceReads target report definition.
countly.membersReport generation contextRead indirectly by report generation flow.
countly.event_groupsReport enrichmentRead indirectly for event-group metadata in generated report content.

Examples​

Preview one report as HTML​

/i/reports/preview?
  api_key=YOUR_API_KEY&
  app_id=6991c75b024cb89cdc04efd2&
  args={"_id":"6262742dbf7392a8bfd8c1f6"}

Limitations​

  • Successful response is HTML, not JSON.
  • Preview generation executes full report query/render logic; large reports can take noticeable time.

Last Updated​

2026-03-07