Skip to content

Report Widget API

The Report Widget API renders charts and saved Data Value, Gauge, and Target widgets from an AutoROICalc report for another website, portal, or application. Public endpoints return a ready-to-use iframe document; authenticated backend endpoints can return HTML or a versioned JSON payload.

Widget access is configured separately for each report and is disabled by default.

AutoROICalc chart, revenue KPI, ROI gauge, and revenue target embedded in a sample workspace

Four supported widget types in a sample host-page layout. All figures are synthetic data for January–June 2026.

Available Widgets

Widget Use it for Configuration
Chart Trends, comparisons, and category shares Choose line, bar, pie, or doughnut, then select and order datasets in each embed URL.
Data Value A headline KPI such as revenue or leads Use a Data Value widget saved in the report layout.
Gauge A metric within a configured range and thresholds Use a Gauge widget saved in the report layout.
Target A calculated value compared with a goal Use a Target widget saved in the report layout.

Choose an Access Mode

Mode Who can load the widget Recommended use
disabled Nobody Reports that should remain inside AutoROICalc
authenticated A trusted backend with a service token Server-rendered portals, WordPress plugins, and private integrations
public Anyone with the generated public URL Browser-safe iframe embeds on websites

Public means accessible by URL

A public widget does not require a viewer to sign in. Only enable public access when the calculated report data is safe for anyone who obtains the URL. Dataset selection and widgetId control presentation, not report access; do not use them to hide confidential datasets.

Configure a Widget in AutoROICalc

  1. Open the saved report.
  2. Open the report sharing menu and select API Widget.
  3. Choose an access mode.
  4. Select Save. When public access is enabled for the first time, AutoROICalc opens the chart configuration before generating the iframe.
  5. Choose the chart type, visible data sets, and their order.
  6. Copy the generated iframe code or public URL.

Select Generate chart widget again to create another iframe with different chart options. Chart choices are stored in each generated URL, not in the report, so one report can provide multiple independently configured widgets. The dialog also lets you preview a generated chart and rotate the report's public URL.

Embed a Public Chart

For public access, AutoROICalc generates an iframe similar to this:

<iframe
  src="https://api.autoroicalc.com/embed/v1/reports/PUBLIC_ID/widgets/chart?chartType=bar&amp;datasetIndexes=2%2C0"
  loading="lazy"
  style="width:100%;height:420px;border:0"
  title="AutoROICalc report chart">
</iframe>

Paste the iframe into the destination page. Each iframe load requests the report widget with calculated report data embedded directly in the returned document. The built-in Refresh button requests an immediate data refresh.

When the report uses advanced layout settings, the embedded chart also inherits its global background and text colors, line thickness and dash, grid color and styling, and legend and scale font settings.

Hovering a chart date matches the in-app report chart: the tooltip groups all visible data-set values for that date and a dashed vertical guide marks the active position.

You can adjust the iframe width and height to fit the destination layout. Keep the generated src URL unchanged.

Public endpoint

GET /embed/v1/reports/{public_id}/widgets/chart?chartType=bar&datasetIndexes=2,0

No access token or service token is needed for this endpoint.

chartType accepts line, bar, pie, or doughnut. datasetIndexes is optional; its comma-separated sequence both selects the report datasets and controls their rendering order. Omit it to render all datasets in their report order. Indexes refer to the report's current dataset positions, so regenerate snippets after adding, removing, or reordering report datasets.

Chart Examples

These screenshots show the actual embedded chart renderer with synthetic sample data. Pie and doughnut slices use distinct category colors with matching legends.

Embedded line chart comparing sample revenue and marketing spend from January to June 2026

Revenue and marketing spend over time — sample data.

Embedded bar chart comparing sample revenue and marketing spend by month

Compare monthly revenue and marketing spend — sample data.

Embedded pie chart with different colors for organic search, paid search, email, and referrals

Leads by acquisition channel — sample data.

Embedded doughnut chart with matching slice and legend colors for four acquisition channels

Leads by acquisition channel as a doughnut chart — sample data.

Embed a Saved Data Value, Gauge, or Target Widget

Create and save the widget in the report's advanced layout first. These embeds use the saved widget's dataset, title, description, style, and range or target settings. The Generate chart widget dialog creates chart snippets; saved widgets use the separate render endpoint.

To discover saved widget IDs, request the authenticated chart JSON payload and inspect availableWidgets. Each entry includes id, type, title, and dataSetIndex. Use the returned id as widgetId; it is not the report ID or dataset index.

For a report with public widget access enabled:

GET /embed/v1/reports/{public_id}/widgets/render?widgetId=revenue-kpi

Use that URL as the iframe's src, replacing PUBLIC_ID and WIDGET_ID with the report's public ID and the saved widget's ID:

<iframe
  src="https://api.autoroicalc.com/embed/v1/reports/PUBLIC_ID/widgets/render?widgetId=WIDGET_ID"
  loading="lazy"
  style="width:100%;height:640px;border:0"
  title="AutoROICalc report widget">
</iframe>

Adjust the height to fit the widget, especially a Target widget with its comparison values. Saved widgets use widgetId rather than the chart endpoint's chartType and datasetIndexes options.

Data Value Example

Embedded Data Value widget showing sample revenue of 100,000 EUR

One headline metric: total revenue of 100,000 EUR — sample data.

Gauge Example

Embedded Gauge widget showing sample marketing ROI of 237.84 percent within a zero-to-400-percent range

Marketing ROI within configured thresholds — sample data.

Target Example

Embedded Target widget comparing sample revenue of 100,000 EUR with a 120,000 EUR goal

Current revenue, target, absolute difference, and percentage difference — sample data.

Authenticated Backend Access

Use authenticated mode when a trusted backend should retrieve the widget without publishing a public URL.

GET /service_token/v1/reports/{report_id}/widgets/chart?chartType=bar&datasetIndexes=2,0
X-Service-Token: <service-token>
Accept: text/html

Example:

curl "https://api.autoroicalc.com/service_token/v1/reports/42/widgets/chart?chartType=bar&datasetIndexes=2,0" \
  -H "X-Service-Token: $AUTOROICALC_SERVICE_TOKEN" \
  -H "Accept: text/html" \
  --output report-widget.html

The report must use authenticated or public widget access. A report with widget access disabled returns 403.

For a saved Data Value, Gauge, or Target widget, use the authenticated render endpoint:

GET /service_token/v1/reports/{report_id}/widgets/render?widgetId=revenue-kpi
X-Service-Token: <service-token>
Accept: text/html

Both rendering endpoints require a service token with the widgets:render scope. Accept: application/json returns the widget payload instead of HTML.

Add refresh=true to bypass the short report-widget cache and calculate fresh report data. Widgets do not continuously poll while open; use Refresh or reload the iframe. Refresh uses the data currently available in AutoROICalc and does not import new source data.

Never expose a service token in browser code

The service-token endpoint is for backend-to-backend requests only. Do not place the service token in HTML, browser JavaScript, a WordPress page, a mobile bundle, or a public repository.

Request the JSON Payload

Send Accept: application/json to the authenticated endpoint when your backend or plugin wants to render the chart itself:

curl "https://api.autoroicalc.com/service_token/v1/reports/42/widgets/chart?chartType=bar&datasetIndexes=0" \
  -H "X-Service-Token: $AUTOROICALC_SERVICE_TOKEN" \
  -H "Accept: application/json"

The response is versioned so clients can validate the schema before rendering it:

{
  "schemaVersion": 1,
  "widget": {
    "type": "chart",
    "appearance": {
      "backgroundColor": "#ffffff",
      "textColor": "#000000",
      "line": {"thickness": 2, "dash": 0},
      "grid": {"color": "#cecece", "thickness": 1, "dash": 0},
      "legend": {"fontSize": 14, "color": "#666666"},
      "scales": {"fontSize": 12, "color": "#666666"}
    },
    "options": {
      "chartType": "bar",
      "filterDataSets": true,
      "filteredDataSetIndexes": [0],
      "adjustItemsOrder": false,
      "orderedDataSetIndexes": []
    }
  },
  "reportData": {
    "reportId": 42,
    "reportName": "Monthly revenue",
    "reportDesc": "Revenue by month",
    "reportChartDateRange": ["January", "February"],
    "reportChartDataSets": [
      {
        "label": "Revenue",
        "color": "#2776a7",
        "data": [1200, 1450]
      }
    ]
  },
  "generatedAt": "2026-09-29T12:00:00+00:00"
}

Clients should check schemaVersion and widget.type before using the payload. Responses also include availableWidgets, listing the report's supported saved widgets and their IDs. The render endpoint uses the same response envelope with widget.type set to dataValue, gauge, or target, and includes the saved widget's id, options, and style.

Configure Access Through the API

The AutoROICalc UI is the simplest way to manage widget access. An authenticated account session can also use these endpoints:

GET  /report/config/{report_id}/widget-api
PUT  /report/config/{report_id}/widget-api
POST /report/config/{report_id}/widget-api/rotate
Authorization: Bearer <access-token>

Set the access mode with:

{
  "access": "public"
}

The settings response for a public report includes the public ID, URL, and ready-to-copy iframe:

{
  "reportId": 42,
  "access": "public",
  "publicId": "4a5d149f-6af3-4fbe-b7f3-b021a979774c",
  "embedPath": "/embed/v1/reports/4a5d149f-6af3-4fbe-b7f3-b021a979774c/widgets/chart",
  "embedUrl": "https://api.autoroicalc.com/embed/v1/reports/4a5d149f-6af3-4fbe-b7f3-b021a979774c/widgets/chart",
  "embedHtml": "<iframe ...></iframe>"
}

Moving away from public immediately revokes the public URL. Enabling public access again creates a new URL.

These settings endpoints only manage widget access. Chart rendering options belong to each public or service-token chart request. Data Value, Gauge, and Target options come from the selected widget saved in the report layout.

Rotate or Revoke a Public URL

Rotate a URL if it was shared with the wrong audience or may have been exposed. Rotation immediately invalidates the previous URL.

After rotation:

  1. Copy the new iframe code.
  2. Replace the old snippet everywhere it was embedded.
  3. Confirm the old URL no longer loads the widget.

To revoke public access without replacing it, change the report to authenticated or disabled.

Response Statuses

Status Meaning
200 Widget or settings returned successfully
400 Unsupported access mode, chart type, dataset selection, or configured widget ID/type
401 Missing or invalid account access token on a settings endpoint
403 Invalid service token, or widget access is disabled for authenticated access
404 Report or public widget was not found
409 Public URL rotation was requested while public access was not enabled
429 Too many public widget requests
503 The chart runtime is temporarily unavailable

Current Scope

Version 1 renders charts and saved Data Value, Gauge, and Target widgets. Other report-designer widgets are not currently available through these embed endpoints.

Report Designer Widgets Report Sharing Service Token API WordPress Dashboard Widgets