Help & Documentation
Open Support Ticket

External Report Download API

This article describes the External Report Download API endpoint available for MI v7.2.1+, which allows downloading an External Report as a file; i.e., PDF, image, Excel, PowerPoint, and more, generated on demand by the source BI tool:

  • /api/element/id/{elementId}/segment/{dimensionId}/download/state/{state}: Discover available formats, generate token for file access, initialize file generation, check generation status, and download the generated file.

The described API endpoint is not available in the API Toolkit and must be accessed via direct API calls.

PREREQUISITES:

  • The Element must be an External Report.
  • The authenticated user must have view access to the Element.
  • The source plugin must support the requested format. Use the formats state to discover what is available for a given Report.

TABLE OF CONTENTS:

  1. Endpoint Overview
  2. Supported File Formats
  3. Download Workflow
    1. List All Available Formats (formats)
    2. Initialize a Download Session (init)
    3. Trigger File Generation (run)
    4. Poll for Completion (check)
    5. Retrieve the File (get)
  4. Request Parameters
  5. Response Fields
  6. Error Responses
  7. End-to-End Example

1. Endpoint Overview

Method: GET

Path: /api/element/id/{elementId}/segment/{dimensionId}/download/state/{state}

A single endpoint drives the entire download workflow. Call the endpoint sequentially through five states to discover available formats, generate the file, and download it. The token returned by the init state is required for run, check, and get.

2. Supported File Formats

The format key passed in format= must match the capability value the plugin advertises for the given External Report. If the format is unavailable, the call returns 400 Invalid format.

Format keyPlugin capabilityFile extensionTypical use
image
IMAGE
.png
Static screenshot
pdf
PDF
.pdf
Standard PDF export
apdf
APDF
.pdf
Accessible (tagged) PDF
ppt
PPT
.pptx
PowerPoint
xls
XLS
.xlsx
Excel
doc
DOC
.docx
Word
csv
CSV
.csv
Tabular data
xml
XML
.xml
XML payload
mhtml
MHTML
.mhtml
Web archive

3. Download Workflow

Each call advances or checks the download session. The session is identified by a token issued in init and expires after 5 minutes.

3.1. List All Available Formats (formats)

GET request to /api/element/id/{elementId}/segment/{dimensionId}/download/state/formats returns the formats supported by the specified External Report, as declared by the source plugin.

Sample response:

{
    "status": "OK",
    "formats": [
        "image", "pdf", "csv", "xls"
    ]
}

3.2. Initialize a Download Session (init)

GET request to  /api/element/id/{elementId}/segment/{dimensionId}/download/state/init creates a short-lived token bound to the calling user. The token is returned URL-encoded.

Sample response:

{
    "status": "OK",
    "token": "<URL-encoded token>"
}

3.3. Trigger File Generation (run)

GET request to  /api/element/id/{elementId}/segment/{dimensionId}/download/state/run?token=<token>&format=<format> generates the requested file by calling the source plugin.

  • The call may take up to 30 minutes, depending on the source BI tool, the Report size, and any configured filters. Poll check from a separate connection while run is in progress.
  • On failure, check and get return ERROR.

Sample response:

{
    "status": "OK"
}

3.4. Poll for Completion (check)

GET request to /api/element/id/{elementId}/segment/{dimensionId}/download/state/check?token=<token> returns one of three statuses:

  • IN PROGRESS: Generation is not yet finished. Continue polling.
  • READY : The file is generated and ready to download.
  • ERROR: Generation failed. Do not call get after ERROR.

Sample response:

{
    "status": "READY"
}

3.5. Retrieve the File (get)

GET request to /api/element/id/{elementId}/segment/{dimensionId}/download/state/get?token=<token>&format=<format> downloads the file as an HTTP attachment. The filename follows the pattern <element-name>.<extension>, with reserved characters stripped.

  • After a successful download, the session is consumed. Calling get again with the same token returns an error.
  • The response Content-Type is set to the file's MIME type, and Content-Disposition is set to attachment; filename="..."
  • If run has not finished, get returns { "status": "IN PROGRESS" }. If run failed, get returns { "status": "ERROR" }.

4. Response Fields

FieldValue typeDescription
status
stringOK, READY, IN PROGRESS, or ERROR depending on state.
formats
array of stringReturned by formats state only. List of format keys the Report supports.
token
stringReturned by init state only. URL-encoded download session token.
message
stringReturned on error responses only. Human-readable error description.

For state=get, a successful response contains the raw file binary; no JSON envelope is returned.

5. Request Parameters

ParameterInRequiredDescription
elementId
pathYesThe Element ID. Must be an External Report.
dimensionId
pathYesThe Dimension Value ID, or 0, for unsegmented Elements.
state
pathYesOne of: formats, init,  run, check, get.
token
queryRequired for run, check, getThe token returned by init, URL-encoded.
format
queryRequired for run, getFormat key from the Supported File Formats table.

6. Error Responses

HTTP codeStatus / MessageCause
400Invalid state
state is not one of the five known values.
400Invalid token
token is missing or malformed.
400No downloads available
The Report has no download capabilities reported by the plugin.
400Invalid format
The supplied format is not in the Report's capability list.
400Not implemented for this Element Type
The Element is not an External Report.
400Download failed
Token expired, generation aborted, or no file produced.
403Element not allowed
The authenticated user does not have view access to the Element.
404Element not found
No Element exists with the given elementId and  dimensionId.

7. End-to-End Example

The following example downloads a PDF for an External Report with elementId = 1042 and dimensionId = 0:

  1. GET /api/element/id/1042/segment/0/download/state/formats ->  { "status": "OK", "formats": ["image", "pdf", "csv"] }
  2. GET /api/element/id/1042/segment/0/download/state/init -> { "status": "OK", "token": "abcDEF123%3D" }
  3. GET /api/element/id/1042/segment/0/download/state/run?token=abcDEF123%3D&format=pdf (may take seconds to minutes) -> { "status": "OK" }
  4. GET /api/element/id/1042/segment/0/download/state/check?token=abcDEF123%3D -> { "status": "READY" }
  5. GET /api/element/id/1042/segment/0/download/state/get?token=abcDEF123%3D&format=pdf ->  200 OK  Content-Type: application/pdf  Content-Disposition: attachment; filename="Sales Dashboard.pdf"  <binary PDF bytes>

After step 5, the session is consumed. Subsequent calls with the same token return an error.

NOTES:

  • Per-format capability is plugin-driven. If a format does not appear in formats, check the source BI tool's connector capabilities or contact the plugin maintainer.
  • Token expires in 5 minutes. Call run promptly after init. If the token expires before run finishes, the file is discarded.
  • Plugin generation can take up to 30 minutes. For large Reports, expect long-running calls. Poll check from a separate connection rather than waiting on run.
  • One download per session. After get succeeds, the session is consumed. To download again, repeat the workflow from  init.
  • External Reports only. Metrics, Reports, Datasets, and Multi-Metric Charts return 400 Not implemented for this Element Type.