Skip to content

Reports

Request a report generation.

Endpoints

Skip to section
POST/v1/reports
GET/v1/reports/{id}/status

Queue a new report request generation.

build

Facts POST /v1/reports

Rate limit
required
Special (10 requests per minute)

Request Body POST /v1/reports

application/json

Definition of the report request. Please note that sense-story-x.0, sense-excel-template-1.0, sense-data-x.0 and qv-data-x.0 types are only for internal use.

Each report request type requires a specific template to be provided:

  • composition-1.0 requires compositionTemplates to be set
  • sense-image-1.0 requires senseImageTemplate to be set
  • sense-sheet-1.0 requires senseSheetTemplate to be set

Each template type supports specific output types:

  • composition-1.0 supports only pdfcomposition and pptxcomposition output types
  • sense-image-1.0 supports pdf and image output types
  • sense-sheet-1.0 supports only pdf output type

Each output type requires a specific output to be provided:

  • pdfcomposition requires pdfCompositionOutput to be set
  • pptxcomposition requires pptxCompositionOutput to be set
  • pdf requires pdfOuput to be set
  • image requires imageOutput to be set

Responses POST /v1/reports

202
application/json
object

Report request accepted.

400
application/json

Bad request, malformed syntax, errors in params or the report request is not valid.

401
application/json

Unauthorized, JWT invalid or not provided.

403
application/json

Forbidden, the user does not have access rights.

404
application/json

Not found.

429
application/json

Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".

500
application/json

Internal server error.

POST/v1/reports

curl "https://your-tenant.us.qlikcloud.com/api/v1/reports" \
 -X POST \
 -H "Authorization: Bearer <API-key>" \
 -H "Content-type: application/json" \
 -d '{"type":"composition-1.0","output":{"type":"pdfcomposition","outputId":"composition1","pdfCompositionOutput":{"pdfOutputs":[{"size":"A4","align":{"vertical":"middle","horizontal":"center"},"resizeType":"autofit","orientation":"A"},{"size":"A4","align":{"vertical":"middle","horizontal":"center"},"resizeType":"autofit","orientation":"A"}]}},"definitions":{"selectionsByState":{"sel1":{"$":[{"values":[{"text":"Arizona","isNumeric":false}],"fieldName":"Region","defaultIsNumeric":false}]}}},"compositionTemplates":[{"type":"sense-sheet-1.0","senseSheetTemplate":{"appId":"2451e58e-a1b9-4047-abf6-315e91d8a610","sheet":{"id":"5ffe3801-1b6d-439d-a849-84d0748358f1"},"selectionsByStateDef":"sel1"}},{"type":"sense-sheet-1.0","senseSheetTemplate":{"appId":"2451e58e-a1b9-4047-abf6-315e91d8a610","sheet":{"id":"ffrxJyA"},"selectionsByStateDef":"sel1"}}]}'

Request POST /v1/reports

{
  "type": "composition-1.0",
  "output": {
    "type": "pdfcomposition",
    "outputId": "composition1",
    "pdfCompositionOutput": {
      "pdfOutputs": [
        {
          "size": "A4",
          "align": {
            "vertical": "middle",
            "horizontal": "center"
          },
          "resizeType": "autofit",
          "orientation": "A"
        },
        {
          "size": "A4",
          "align": {
            "vertical": "middle",
            "horizontal": "center"
          },
          "resizeType": "autofit",
          "orientation": "A"
        }
      ]
    }
  },
  "definitions": {
    "selectionsByState": {
      "sel1": {
        "$": [
          {
            "values": [
              {
                "text": "Arizona",
                "isNumeric": false
              }
            ],
            "fieldName": "Region",
            "defaultIsNumeric": false
          }
        ]
      }
    }
  },
  "compositionTemplates": [
    {
      "type": "sense-sheet-1.0",
      "senseSheetTemplate": {
        "appId": "2451e58e-a1b9-4047-abf6-315e91d8a610",
        "sheet": {
          "id": "5ffe3801-1b6d-439d-a849-84d0748358f1"
        },
        "selectionsByStateDef": "sel1"
      }
    },
    {
      "type": "sense-sheet-1.0",
      "senseSheetTemplate": {
        "appId": "2451e58e-a1b9-4047-abf6-315e91d8a610",
        "sheet": {
          "id": "ffrxJyA"
        },
        "selectionsByStateDef": "sel1"
      }
    }
  ]
}

Get report request processing status.

build

Facts GET /v1/reports/{id}/status

Rate limit
required
Tier 1 (1000 requests per minute)

Path Parameters GET /v1/reports/{id}/status

id
required
string

Identifier of the request.

Responses GET /v1/reports/{id}/status

200
application/json

Returns the request processing status.

400
application/json

Bad request. Malformed syntax, errors in params.

401
application/json

Unauthorized, JWT invalid or not provided.

403
application/json

Forbidden, user did not authenticate.

404
application/json

Not found.

429
application/json

Too many request. Indicates the user has sent too many requests in a given amount of time, aka "rate limiting".

500
application/json

Internal server error.

GET/v1/reports/{id}/status

curl "https://your-tenant.us.qlikcloud.com/api/v1/reports/{id}/status" \
 -H "Authorization: Bearer <API-key>"

Response GET /v1/reports/{id}/status

{
  "status": "done",
  "results": [
    {
      "location": "https://qlikcloud.com:443/api/v1/temp-contents/619baab68023910001efcb86?inline=1",
      "outputId": "output1"
    }
  ],
  "statusLocation": "/reports/01562a37-23e3-4b43-865d-84c26122276c/status",
  "resolutionAttempts": 1
}

AppError

Error in resource handling

Properties

appId
string

app id

method
string

The method that is failing.

parameters
object

Parameters of method that fails.

AppErrors

Array<AppError>

Errors occurring when dealing with the app.

Properties

appId
string

app id

method
string

The method that is failing.

parameters
object

Parameters of method that fails.

CallBackAction

The callback to be performed once the report is done.

Properties

httpRequest

Http callback. The provided uri will be called once the report is done.

ComposableTemplate

Properties

type
required
string

Template type and version using semantic versioning. It must have the following name convention, dashed-separated-template-name-MAJOR.MINOR

Enum:

sense-image-1.0

sense-sheet-1.0

senseImageTemplate

Used to export a single visualization as pdf or png.

senseSheetTemplate

Used to export a sheet as pdf.

Definitions

Definitions of common properties that are shared between templates, e.g. selectionsByState can be the same for all templates within a composition of templates.

Properties

selectionsByState
object

It maps an ID to a selectionsByState object.

DocProperties

Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored.

Properties

title
string

No description

author
string

No description

subject
string

No description

Error

object

Properties

errors

Errors occured during report generation.

ExcelOutput

Output to be used to export a excel template.

Properties

outFormat
default='xlsx'
string

The image format of the report to be produced.

Enum:

xlsx

ExportError

object

Error occured during report generation.

Properties

code
required
string

The unique code for the error

  • "REP-400000" Bad request. The server could not understand the request due to invalid syntax.
  • "REP-400008" Selections error.
  • "REP-400009" Maximum 16384 columns limit exceeded. Download data in a visualization can't generate an .xlsx file due to limitations to the number of columns you can download.
  • "REP-400010" Maximum 1048566 rows limit exceeded. Download data in a visualization can't generate an .xlsx file due to limitations to the number of rows you can download.
  • "REP-400011" The size of the downloaded Excel file exceed 100 MB limit. Download data in a visualization can't generate an .xlsx file due to limitations to the amount of data you can download.
  • "REP-400015" Bad request in enigma request. The patch value has invalid JSON format.
  • "REP-401000" Unauthorized. The client must authenticate itself to get the requested response.
  • "REP-401001" Unauthorized, bad JWT.
  • "REP-403000" Forbidden. The client does not have access rights to the content.
  • "REP-403001" App forbidden, the user does not have read permission on the app.
  • "REP-403002" Chart type not supported.
  • "REP-404000" Not found. The server can not find the requested resource.
  • "REP-404001" App not found, the app does not exist or it has been deleted.
  • "REP-404002" Chart not found, the chart does not exist or it has been deleted.
  • "REP-404003" Sheet not found, the sheet does not exist or it has been deleted or it is unavailable.
  • "REP-404004" Story not found, the story does not exist or it has been deleted or it is unavailable.
  • "REP-429000" Too many request. The user has sent too many requests in a given amount of time ("rate limiting").
  • "REP-429012" Exceeded max session tenant quota. A tenant has opened too many different sessions at the same time.
  • "REP-429014" Reporting service was not able to return inside of request export deadline. Too many request at the same time for the same tenant.
  • "REP-429016" Exceeded max session tenant quota per day.
  • "REP-500000" Fail to resolve resource.
  • "REP-500006" Fail to get report session parameters.
  • "REP-503005" Engine unavailable, qix-sessions error no engines available.
  • "REP-503013" Session unavailable. The engine session used to create the report is unavailable.
  • "REP-500100" Image rendering generic error on Sense client.
  • "REP-500101" Image rendering could not set cookies error on Sense client.
  • "REP-400102" Image rendering invalid strategy error on Sense client.
  • "REP-500103" Image rendering JS timeout error on Sense client.
  • "REP-500104" Image rendering load URL timeout error on Sense client.
  • "REP-500105" Image rendering max paint attempts exceeded error on Sense client.
  • "REP-500106" Image rendering max JS attempts exceeded error on Sense client.
  • "REP-500107" Image rendering render timeout error on Sense client.
  • "REP-500108" Image rendering JS failure due to timeout error on Sense client.
  • "REP-500109" Image rendering generic JS failure error on Sense client.
  • "REP-400029" Reload Entitlement Limit Reached.
meta

Define the export error metadata. Each property is filled if it is related to the export error type.

title
required
string

A summary in english explaining what went wrong.

detail
string

Optional. MAY be used to provide more concrete details.

ExportErrors

Array<ExportError>

Errors occured during report generation.

Properties

code
required
string

The unique code for the error

  • "REP-400000" Bad request. The server could not understand the request due to invalid syntax.
  • "REP-400008" Selections error.
  • "REP-400009" Maximum 16384 columns limit exceeded. Download data in a visualization can't generate an .xlsx file due to limitations to the number of columns you can download.
  • "REP-400010" Maximum 1048566 rows limit exceeded. Download data in a visualization can't generate an .xlsx file due to limitations to the number of rows you can download.
  • "REP-400011" The size of the downloaded Excel file exceed 100 MB limit. Download data in a visualization can't generate an .xlsx file due to limitations to the amount of data you can download.
  • "REP-400015" Bad request in enigma request. The patch value has invalid JSON format.
  • "REP-401000" Unauthorized. The client must authenticate itself to get the requested response.
  • "REP-401001" Unauthorized, bad JWT.
  • "REP-403000" Forbidden. The client does not have access rights to the content.
  • "REP-403001" App forbidden, the user does not have read permission on the app.
  • "REP-403002" Chart type not supported.
  • "REP-404000" Not found. The server can not find the requested resource.
  • "REP-404001" App not found, the app does not exist or it has been deleted.
  • "REP-404002" Chart not found, the chart does not exist or it has been deleted.
  • "REP-404003" Sheet not found, the sheet does not exist or it has been deleted or it is unavailable.
  • "REP-404004" Story not found, the story does not exist or it has been deleted or it is unavailable.
  • "REP-429000" Too many request. The user has sent too many requests in a given amount of time ("rate limiting").
  • "REP-429012" Exceeded max session tenant quota. A tenant has opened too many different sessions at the same time.
  • "REP-429014" Reporting service was not able to return inside of request export deadline. Too many request at the same time for the same tenant.
  • "REP-429016" Exceeded max session tenant quota per day.
  • "REP-500000" Fail to resolve resource.
  • "REP-500006" Fail to get report session parameters.
  • "REP-503005" Engine unavailable, qix-sessions error no engines available.
  • "REP-503013" Session unavailable. The engine session used to create the report is unavailable.
  • "REP-500100" Image rendering generic error on Sense client.
  • "REP-500101" Image rendering could not set cookies error on Sense client.
  • "REP-400102" Image rendering invalid strategy error on Sense client.
  • "REP-500103" Image rendering JS timeout error on Sense client.
  • "REP-500104" Image rendering load URL timeout error on Sense client.
  • "REP-500105" Image rendering max paint attempts exceeded error on Sense client.
  • "REP-500106" Image rendering max JS attempts exceeded error on Sense client.
  • "REP-500107" Image rendering render timeout error on Sense client.
  • "REP-500108" Image rendering JS failure due to timeout error on Sense client.
  • "REP-500109" Image rendering generic JS failure error on Sense client.
  • "REP-400029" Reload Entitlement Limit Reached.
meta

Define the export error metadata. Each property is filled if it is related to the export error type.

title
required
string

A summary in english explaining what went wrong.

detail
string

Optional. MAY be used to provide more concrete details.

Float64

number<float64>

HttpRequest

Http callback. The provided uri will be called once the report is done.

Properties

uri
string

URI of the request.

ImageOutput

Output to be used to export a single visualization as image.

Properties

outDpi
maximum=1000
integer<int32>

Image resolution in DPI (default 96 DPI).

outZoom
number<float>

The scale factor to be applied in image scaling. A zoom greater than 5 will not be applied to the device pixel ratio which will remain fixed at 5.

outFormat
default='png'
string

The image format of the report to be produced.

Enum:

png

jsondata

Meta

Define the request metadata. It includes priority, deadline and future settings on execution policy of the request.

Properties

outputTtl
string<iso8601>

Time to live of the final result artifacts in ISO8601 duration format. After that duration the request and underlying output files will not be guaranteed to be available. Default is 1 hour.

exportDeadline
string<iso8601>

The maximum interval, starting from the time the API request is received, within which a report must be produced, past this interval the report generation fails. The default value is 10 minutes, the maximum allowed value is 2 hours.

MetaExportError

Define the export error metadata. Each property is filled if it is related to the export error type.

Properties

appErrors

Errors occurring when dealing with the app.

selectionErrors

Errors occurring in selections.

NxPatch

Patches to apply to sense charts. Patches are soft properties meaning that are not persistent and they live within a session.

Properties

qOp
required
string

No description

Enum:

add

remove

replace

qPath
required
string

Path to the property to add, remove or replace.

qValue
string

Corresponds to the value of the property to add or to the new value of the property to update.

OutputItem

Properties

type
required
string

The generated report type.

Each template type supports specific output types:

  • composition-1.0 supports only pdfcomposition and pptxcomposition output types
  • excel-1.0 supports only excel output type
  • sense-image-1.0 supports pdf and image output types
  • sense-sheet-1.0 supports only pdf output type

Each output type requires a specific output to be provided:

  • excel requires excelOutput to be set
  • pdfcomposition requires pdfCompositionOutput to be set
  • pptxcomposition requires pptxCompositionOutput to be set
  • pdf requires pdfOuput to be set
  • image requires imageOutput to be set
  • csv doesn't have csv output.

Enum:

image

pdf

xlsx

jsondata

pdfcomposition

excel

pptx

pptxcomposition

csv

outputId
required
string

The output identifier which uniquely identifies an output (PDF, image etc.) within the same request. It does not need to be a GUID. No spaces and colons are allowed in the outputId string.

pdfOutput

Output to be used to export a single visualization or a sheet as pdf.

pptxOutput

Output to be used to export a single visualization or a sheet as PowerPoint presentation.

excelOutput

Output to be used to export a excel template.

imageOutput

Output to be used to export a single visualization as image.

callBackAction

The callback to be performed once the report is done.

pdfCompositionOutput

Output to be used to export a composition of templates as pdf.

pptxCompositionOutput

Output to be used to export a composition of templates as pptx.

PdfCompositionOutput

Output to be used to export a composition of templates as pdf.

Properties

pdfOutputs

The ordered list of PDF outputs, the number must match the composable templates.

properties

Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored.

PdfOutput

Output to be used to export a single visualization or a sheet as pdf.

Properties

size
default='A4'
string

Size of the pdf page.

Enum:

A1

A2

A3

A4

A5

A6

Letter

Legal

Tabloid

align

Content alignment.

properties

Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored.

resizeData
object

The area where the object (eg. sheet, chart) is printed. Required in case of "fit" resizeType.

resizeType
default='none'
string

The type of resize to be performed:

  • none is used to export a visualization, sheet or story as is (e.g. normal size), regardless of its size. This may result in cropping.
  • autofit automatically fits the visualization, sheet or story into the output size (i.e. A4, A3 etc.). Any provided resizeData parameter will be ignored for this configuration.
  • fit fits the visualization, sheet or story into the area specified in resizeData. The content will be rescaled to fit in that area.

Enum:

none

autofit

fit

orientation
default='P'
string

P for portrait, L for landscape and A for auto-detect. Auto-detect sets the orientation depending on the content width and height proportions: if content width > height the orientation is automatically set to landscape, portrait otherwise.

Enum:

P

L

A

imageRenderingDpi
default=300, maximum=1000
number<int32>

This value is used for rendered images only, set to a default of 300 dpi.

PptxCompositionOutput

Output to be used to export a composition of templates as pptx.

Properties

pptxOutput

Output to be used to export a single visualization or a sheet as PowerPoint presentation.

PptxOutput

Output to be used to export a single visualization or a sheet as PowerPoint presentation.

Properties

size
default='Widescreen'
string

Size of the PowerPoint slide:

  • Widescreen: 960x540
  • OnScreen: 720x540
  • OnScreen16x9: 720x405
  • OnScreen16x10: 720x450

Enum:

Widescreen

OnScreen

OnScreen16x9

OnScreen16x10

properties

Properties of the document. In case of multiple composition, only properties specified in the composition output are taken and the ones specified in each output item are ignored.

resizeType
default='autofit'
string

The type of resize to be performed. Autofit automatically fits the visualization, sheet or story into the output size (i.e. Widescreen, OnScreen etc.).

Enum:

autofit

orientation
default='L'
string

L for landscape, P for portrait and A for auto-detect. Auto-detect sets landscape, the default PowerPoint orientation.

Enum:

L

P

A

imageRenderingDpi
default=200, maximum=1000
number<int32>

This value is used for rendered images only, set to a default of 200 dpi.

QFieldValue

In order to apply a selection just one of text/number needs to be set, this must be associated with the correct isNumeric bool. In some scenarios both text and number may be set.

Properties

text
string

String value of the field value.

number

No description

isNumeric
boolean

IsNumeric tells whether the field value is text or number. Default value is equal to defaultIsNumeric property in QSelection.

QSelection

Properties

values
required

The values of the field to be selected.

fieldName
required
string

The name of the field to be selected.

defaultIsNumeric
required
boolean

Default value that QFieldValue isNumeric property takes if missing.

Reason

Properties

traceId
string

No description

outputId
string

The output identifier which uniquely identifies an output (PDF, image etc.) within the same request.

exportErrors

Errors occured during report generation.

ReportRequest

Properties

meta

Define the request metadata. It includes priority, deadline and future settings on execution policy of the request.

type
required
string

Template type and version using semantic versioning. It must have the following name convention: dashed-separated-template-name-MAJOR.MINOR. Please note that sense-story-x.0, sense-excel-template-1.0, sense-data-x.0 and qv-data-x.0 are only for internal use.

Each type requires a specific template to be provided:

  • composition-1.0 requires compositionTemplates to be set
  • sense-excel-template-1.0 requires senseExcelTemplate to be set
  • sense-image-1.0 requires senseImageTemplate to be set
  • sense-sheet-1.0 requires senseSheetTemplate to be set

Each template type supports specific output types:

  • composition-1.0 supports only pdfcomposition output type
  • sense-excel-template-1.0 supports only excel output type
  • sense-image-1.0 supports pdf and png output types
  • sense-sheet-1.0 supports only pdf output type

Enum:

composition-1.0

sense-image-1.0

sense-data-1.0

sense-sheet-1.0

sense-story-1.0

qv-data-1.0

qv-data-2.0

sense-excel-template-1.0

output
required

No description

definitions

Definitions of common properties that are shared between templates, e.g. selectionsByState can be the same for all templates within a composition of templates.

senseImageTemplate

Used to export a single visualization as pdf or png.

senseSheetTemplate

Used to export a sheet as pdf.

compositionTemplates

Composition of senseSheetTemplate and/or senseImageTemplate templates.

ReportStatus

object

Properties

status
required
string

Status of the requested report.

Enum:

queued

processing

done

failed

aborted

visiting

aborting

reasons

Present when status is failed.

results

Present when the status is "done".

statusLocation
string<uri>

Relative path to status location.

resolutionAttempts
integer<int32>

Count how many times the resolution of this report was attempted.

Result

object

Result and info about the generated report.

Properties

location
required
string<uri>

Location to download the generated report.

outputId
required
string

The output identifier which uniquely identifies an output (PDF, image etc.) within the same request.

exportErrors

Errors occured during report generation.

SelectionError

Selection error related to a fieldName. The field name is missing or some of his selection values are missing or a state is missing

Properties

detail
string

Details about the field selection error.

errorType
string

No description

Enum:

fieldMissing

fieldValuesMissing

stateMissing

fieldName
string

The field name that is missing.

stateName
string

The state name that is missing.

missingValues

No description

isFieldNameMissing
deprecated
boolean

Deprecated, use errorType instead. True if the fieldName is missing. The missingValues array is empty in this case

SelectionErrors

Array<SelectionError>

Errors occurring in selections.

Properties

detail
string

Details about the field selection error.

errorType
string

No description

Enum:

fieldMissing

fieldValuesMissing

stateMissing

fieldName
string

The field name that is missing.

stateName
string

The state name that is missing.

missingValues

No description

isFieldNameMissing
deprecated
boolean

Deprecated, use errorType instead. True if the fieldName is missing. The missingValues array is empty in this case

SelectionStrategy

string

Enum:

failOnErrors

ignoreErrorsReturnDetails

ignoreErrorsNoDetails

SenseImageTemplate

Used to export a single visualization as pdf or png.

Properties

appId
required
string

No description

visualization

No description

selectionStrategy
default='ignoreErrorsNoDetails'

No description

Enum:

failOnErrors

ignoreErrorsReturnDetails

ignoreErrorsNoDetails

selectionsByState
object

Map of selections to apply by state. Maximum number of states allowed is 125. Maximum number of fields allowed is 125 and maximum number of overall field values allowed is 150000.

selectionsByStateDef
string

The definition ID referring to a selectionsByState definition declared in definitions.

SenseSheetTemplate

Used to export a sheet as pdf.

Properties

appId
required
string

No description

sheet
required

It refers to the Sense Sheet to be exported. Note that if widthPx and heightPx are not specified, default values will be applied depending on the actual size and layout properties of the Sense Sheet object.

selectionStrategy
default='ignoreErrorsNoDetails'

No description

Enum:

failOnErrors

ignoreErrorsReturnDetails

ignoreErrorsNoDetails

selectionsByState
object

Map of selections to apply by state. Maximum number of states allowed is 125. Maximum number of fields allowed is 125 and maximum number of overall field values allowed is 150000.

selectionsByStateDef
string

The definition ID referring to a selectionsByState definition declared in definitions.

Sheet

It refers to the Sense Sheet to be exported. Note that if widthPx and heightPx are not specified, default values will be applied depending on the actual size and layout properties of the Sense Sheet object.

Properties

id
required
string

The id of the sheet.

jsOpts
object

A JSON object that is passed as-is to the mashup page while rendering, this will be applied to all charts within the sheet. It includes properties of the whole sheet such as theme, gradient etc.

widthPx
minimum=20, maximum=4000
number<float>

The width of the sheet in pixels. Default value is: - 1680 pixels for responsive sheet - 1120 pixels for extended sheet - same width set in sheet properties for custom sheet

heightPx
minimum=20, maximum=4000
number<float>

The height of the sheet in pixels. Default value is: - 1120 pixels for responsive sheet - 1680 pixels for extended sheet - same height set in sheet properties for custom sheet

jsOptsById
object

A map for applying jsOpts to specific visualization IDs within the sheet.

patchesById
object

A map for applying soft properties, aka patches, to specific visualization IDs within the sheet.

Visualization

Properties

id
required
string

The sense visualization id or json definition.

type
string

Choose visualization to export an image of a sense chart, sessionobject for a visualization to be created on-the-fly. An empty value leads to the type being inferred by its id.

Enum:

visualization

sessionobject

jsOpts
object

A JSON object that is passed as-is to the mashup page while rendering.

patches

Soft properties, aka patches, to be applied to the visualization.

widthPx
required, minimum=5, maximum=4000
number<float>

Width in pixels.

heightPx
required, minimum=5, maximum=4000
number<float>

Height in pixels.

v0.879.8
Was this page helpful?