--- updatedAt: 2026-04-24T16:37:26.000Z agentTools: projectIndex: https://developers.cloudbeds.com/llms.txt --- # Query report data and export to file Request a file export of data from any report json that is not created Query report data from a report that is not created Based on the report `type` sent in the request, the data structure returned may have multiple formats. Mode: - Export: 100000 Records ## Types #### List ``` { ... "columns": ... "settings": { ... "totals": false, "transpose": false, } } ``` #### List (Totals) ``` { ... "columns": ... "settings": { ... "totals": true, "transpose": false, } } ``` #### PeriodList ``` { ... "columns": ... "periods": ... "settings": { ... "totals": false, "transpose": true|false, } } ``` #### Summary ``` { ... "columns": ... "group_rows": ... "settings": { ... "totals": false, "transpose": true|false, } } ``` #### Summary (Totals) ``` { ... "columns": ... "group_rows": ... "settings": { ... "totals": true "transpose: true|false, } } ``` #### PeriodSummary ``` { ... "columns": ... "group_rows": ... "periods": ... "settings": { ... "totals": false, "transpose": true|false, } } ``` #### Pivot ``` { ... "columns": ... "group_rows": ... "group_columns": ... "settings": { ... "totals": false, "transpose": true|false } } ``` #### Pivot (Totals) ``` { ... "columns": ... "group_rows": ... "group_columns": ... "settings": { ... "totals": true, "transpose": true|false, } } ``` ## Data | Type | Headers | Index | Records | Group Rows | Group Columns | Totals | Periods | Transpose | | -------------------- | ------- | ------ | ------- | ---------- | ------------- | ------ | ------- | --------- | | **List** | Yes | No | Yes | No | No | No | No | No | | **List (Totals)** | Yes | No | Yes | No | No | Yes | No | No | | **PeriodList** | Yes | Yes | Yes | No | No | No | Yes | Yes | | **Summary** | Yes | Yes | Yes | Yes | No | No | No | Yes | | **Summary (Details)** | Yes | Yes | Yes | Yes | No | Yes | No | No | | **Summary (Totals)** | Yes | Yes | Yes | Yes | No | Yes | No | Yes | | **PeriodSummary** | Yes | Yes | Yes | Yes | No | No | Yes | Yes | | **Pivot** | Yes | Yes | Yes | Yes | Yes | No | No | Yes | | **Pivot (Totals)** | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes | # OpenAPI definition ````json { "info": { "description": "#### The Cloudbeds Data Insights API provides programmatic methods to access report data in [Data Insights](https://www.cloudbeds.com/measure-success/). With the Cloudbeds Data Insights API, you can:\n\n- Build custom reports to display Cloudbeds data.\n- Automate complex reporting tasks to save time.\n- Integrate your Cloudbeds data with other business applications.\n- Schedule your reports to your email in a custom frequency\n- Access stock/custom reports created by Cloudbeds\n- And many others\n- Export Request has a limit of 100000 records\n- Data and Summary requests has a limit of 100 records when the mode is Preview\n- Data and Summary requests has a limit of 12000 records when the mode is Run\n\n*Note: The API return application/json*.", "version": "1.1", "title": "Data Insights API", "termsOfService": "https://www.cloudbeds.com/terms/api/", "contact": { "email": "support@cloudbeds.com" }, "license": { "name": "Cloudbeds", "url": "https://www.cloudbeds.com/" } }, "components": { "securitySchemes": { "Authorization": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "##### Authorization refers to the process of granting a user or application access permissions to Cloudbeds data and features.\n\nTo authenticate your users, your App will need to implement an [authorization code flow](https://datatracker.ietf.org/doc/html/rfc6749#section-4.1).\n[Cloudbeds API Authentication](https://hotels.cloudbeds.com/api/docs/#api-Authentication) lets you direct your users to an authorization dialog on Cloudbeds.\nFrom there, the primary Cloudbeds experience will show the authorization dialog and handle the authorization on behalf of your App.\nYour users will be able to authorize or decline.\nAfter the user makes their choice, Cloudbeds will redirect the user to your App, where you can exchange the authorization code for an access token (if the user authorized your App), or handle a rejection (if the user did not authorize your App).\n\nIf using a cloudbeds API key, you can pass it as a header with the following format: `X-API-KEY: `\n\n###### Cloudbeds implements the [OAuth 2.0](https://integrations.cloudbeds.com/hc/en-us/articles/360006450433-OAuth-2-0) authorization framework." } }, "schemas": { "ErrorContent": { "type": "object", "properties": { "code": { "type": "integer", "description": "Error code" }, "status": { "type": "string", "description": "Error status" }, "description": { "type": "string", "description": "Error description" }, "message": { "type": "object", "description": "Error message" } } }, "Error": { "type": "object", "properties": { "error": { "$ref": "#/components/schemas/ErrorContent" } } }, "ReportCDF": { "type": "object", "properties": { "type": { "type": "string", "default": "default", "enum": [ "default", "custom" ], "description": "Report cdf type", "example": "default" }, "column": { "type": "string", "description": "Report cdf name", "example": "credit_amount" }, "multi_level_id": { "type": "integer", "enum": [ 1, 2, 3, 4 ], "description": "Multi-level where CDF is located" } }, "required": [ "column" ] }, "ReportColumns": { "type": "object", "properties": { "cdf": { "example": { "type": "default", "column": "credit_amount" }, "allOf": [ { "$ref": "#/components/schemas/ReportCDF" } ] }, "metrics": { "type": "array", "minItems": 1, "description": "Report column metrics", "items": { "type": "string", "enum": [ "sum", "mean", "max", "min", "count", "std", "var" ], "example": "sum" } } }, "required": [ "cdf" ] }, "ReportGroup": { "type": "object", "properties": { "cdf": { "$ref": "#/components/schemas/ReportCDF" }, "modifier": { "type": "string", "enum": [ "second", "minute", "hour", "day", "month", "year", "week", "weekday", "d", "m", "time_hour", "time_minute", "time_second" ], "description": "Report group modifier" } }, "required": [ "cdf" ] }, "ReportPeriod": { "type": "object", "properties": { "cdf": { "$ref": "#/components/schemas/ReportCDF" }, "name": { "type": "string", "description": "Label for a period", "example": "Month-To-Date" }, "id": { "type": "string", "readOnly": true, "description": "machine name of period (auto-generated)", "example": "start_of_last_year_to_today" }, "start": { "type": "string", "description": "The beginning date or relative date of a period. When both start and end dates are relative dates, the difference between today and the end date is subtracted from the start date.", "example": "'2014-12-22T03:12:58'|'start_current_year'" }, "end": { "type": "string", "description": "The beginning date or relative date of a period", "example": "'2014-12-22T03:12:58'|'today'" }, "start_relative_to_end": { "type": "boolean", "description": "If true, relative start date will be relative to the end date instead of today,e.g. if end date is 2023-01-01, a start date of yesterday would be 2022-12-31", "example": false } }, "required": [ "cdf", "end", "name", "start" ] }, "ReportFilter": { "type": "object", "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/ReportFilter" } }, "or": { "type": "array", "items": { "$ref": "#/components/schemas/ReportFilter" } }, "cdf": { "description": "Filter cdf for the rule", "allOf": [ { "$ref": "#/components/schemas/ReportCDF" } ] }, "operator": { "type": "string", "enum": [ "begins", "not_begins", "ends", "not_ends", "contains", "not_contains", "list_contains", "not_list_contains", "is_null", "is_not_null", "is_empty", "is_not_empty", "equals", "not_equals", "greater_than", "less_than", "less_than_or_equal", "greater_than_or_equal" ], "description": "Filter operator value" }, "value": { "description": "Filter value", "nullable": true } } }, "ReportComparisonFilters": { "type": "object", "properties": { "and": { "type": "array", "minItems": 1, "maxItems": 4, "items": { "$ref": "#/components/schemas/ReportFilter" } } } }, "ReportComparison": { "type": "object", "properties": { "name": { "type": "string", "description": "Label for a Comparison", "example": "Range 1" }, "id": { "type": "string", "readOnly": true, "description": "machine name of comparison (auto-generated)", "example": "range_1" }, "filters": { "default": null, "minItems": 1, "maxItems": 1, "description": "Report filters", "example": { "and": [ { "cdf": { "type": "default", "column": "checkin_date" }, "operator": "less_than_or_equal", "value": "today" }, { "or": [ { "cdf": { "type": "default", "column": "booking_datetime" }, "operator": "less_than_or_equal", "value": "2021-10-19T00:00:00" }, { "cdf": { "type": "default", "column": "booking_datetime" }, "operator": "greater_than_or_equal", "value": "2020-10-19T00:00:00" } ] } ] }, "allOf": [ { "$ref": "#/components/schemas/ReportComparisonFilters" } ], "nullable": true } }, "required": [ "name" ] }, "ReportFilters": { "type": "object", "properties": { "and": { "type": "array", "items": { "$ref": "#/components/schemas/ReportFilter" } }, "or": { "type": "array", "items": { "$ref": "#/components/schemas/ReportFilter" } } } }, "ReportSort": { "type": "object", "properties": { "cdf": { "$ref": "#/components/schemas/ReportCDF" }, "direction": { "type": "string", "enum": [ "asc", "desc" ], "example": "asc", "description": "Report sort direction" } }, "required": [ "cdf", "direction" ] }, "ReportSettings": { "type": "object", "properties": { "details": { "type": "boolean", "description": "Report details", "example": false }, "totals": { "type": "boolean", "description": "Report totals", "example": false }, "transpose": { "type": "boolean", "description": "Transpose Report", "example": false } }, "required": [ "details", "totals" ] }, "ReportFormats": { "type": "object", "properties": { "date": { "type": "string", "default": "YYYY-MM-DD", "enum": [ "YYYY-MM-DD", "YYYY.MM.DD", "YYYY/MM/DD", "YYYY-DD-MM", "YYYY.DD.MM", "YYYY/DD/MM", "MM-YYYY-DD", "MM.YYYY.DD", "MM/YYYY/DD", "MM-DD-YYYY", "MM.DD.YYYY", "MM/DD/YYYY", "DD-YYYY-MM", "DD.YYYY.MM", "DD/YYYY/MM", "DD-MM-YYYY", "DD.MM.YYYY", "DD/MM/YYYY", null ], "example": "YYYY-MM-DD", "description": "Date Format that will be applied in the export. The default is YYYY-MM-DD", "nullable": true } } }, "CustomCdfFormula": { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "cdf", "separator", "operator", "operand", "parenthesis" ] }, "value": { "type": "string", "minLength": 1, "description": "- If the kind is *cdf* the value must be a valid cdf.\n - If the kind is *separator* the supported values are any.\n - If the kind is *operator* the supported values are: ['+', '-', '*', '/'].\n - If the kind is *operand* the supported values are numbers.\n - If the kind is *parenthesis* the supported values are: ( or )." }, "metric": { "type": "string", "default": null, "enum": [ "sum", "mean", "max", "min", "count", "std", "var", null ], "nullable": true } }, "required": [ "kind", "value" ] }, "ReportCustomCdf": { "type": "object", "properties": { "id": { "type": "integer", "readOnly": true, "description": "Report custom cdf id", "example": "1" }, "column": { "type": "string", "readOnly": true, "description": "Report custom cdf column", "example": "full_address" }, "name": { "type": "string", "minLength": 1, "description": "Report custom cdf name", "example": "Full address" }, "description": { "type": "string", "default": null, "description": "Report custom cdf description", "example": "CDF with the full address information", "nullable": true }, "formula": { "type": "array", "items": { "$ref": "#/components/schemas/CustomCdfFormula" } }, "kind": { "type": "string", "enum": [ "String", "Number", "Dynamic" ], "description": "Report custom cdf kind", "example": "String" }, "created_at": { "type": "string", "readOnly": true, "description": "Report custom cdf created at" }, "updated_at": { "type": "string", "readOnly": true, "description": "Report custom cdf updated at" }, "format": { "type": "string", "enum": [ "number", "currency", "percentage", null ], "description": "Custom Cdf Numeric format (valid for Number and Dynamic only)", "example": "currency", "nullable": true } }, "required": [ "formula", "kind", "name" ] }, "ReportExport": { "type": "object", "properties": { "url": { "type": "string", "format": "url", "readOnly": true, "example": "https://...", "description": "Url to get the exported report" }, "format": { "type": "string", "enum": [ "xlsx", "csv", "json" ], "readOnly": true, "example": "xlsx", "description": "Format: should be either 'xlsx', 'csv' or 'json'" }, "view": { "type": "string", "enum": [ "details", "formatted" ], "readOnly": true, "example": "details", "description": "View: should be either 'formatted' or 'details'" }, "filename": { "type": "string", "readOnly": true, "description": "Name of the file exported" }, "generated_at": { "type": "string", "readOnly": true, "description": "File generated at" } } }, "ReportQueryExport": { "type": "object", "properties": { "title": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Report title", "example": "Report title" }, "property_ids": { "type": "array", "minItems": 1, "description": "Report property ids", "items": { "type": "integer", "minimum": 1, "description": "Property id", "example": "1" } }, "dataset_id": { "type": "integer", "enum": [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ], "description": "Dataset id", "example": 1 }, "columns": { "minItems": 1, "description": "Report columns", "type": "array", "items": { "$ref": "#/components/schemas/ReportColumns" } }, "group_rows": { "default": null, "minItems": 1, "maxItems": 3, "description": "Report group rows", "type": "array", "items": { "$ref": "#/components/schemas/ReportGroup" }, "nullable": true }, "group_columns": { "default": null, "minItems": 1, "maxItems": 2, "description": "Report group columns", "type": "array", "items": { "$ref": "#/components/schemas/ReportGroup" }, "nullable": true }, "custom_cdfs": { "default": null, "description": "Report custom cdfs", "type": "array", "items": { "$ref": "#/components/schemas/ReportCustomCdf" }, "nullable": true }, "filters": { "default": null, "minItems": 1, "description": "Report filters", "example": { "and": [ { "cdf": { "type": "default", "column": "checkin_date" }, "operator": "less_than_or_equal", "value": "today" }, { "or": [ { "cdf": { "type": "default", "column": "booking_datetime" }, "operator": "less_than_or_equal", "value": "2021-10-19T00:00:00" }, { "cdf": { "type": "default", "column": "booking_datetime" }, "operator": "greater_than_or_equal", "value": "2020-10-19T00:00:00" } ] } ] }, "allOf": [ { "$ref": "#/components/schemas/ReportFilters" } ], "nullable": true }, "sort": { "default": null, "minItems": 1, "description": "Report sort", "type": "array", "items": { "$ref": "#/components/schemas/ReportSort" }, "nullable": true }, "settings": { "description": "Report settings", "allOf": [ { "$ref": "#/components/schemas/ReportSettings" } ], "nullable": true }, "periods": { "default": null, "maxItems": 3, "description": "Periods to compare", "type": "array", "items": { "$ref": "#/components/schemas/ReportPeriod" }, "nullable": true }, "formats": { "description": "Formatting options of the report", "allOf": [ { "$ref": "#/components/schemas/ReportFormats" } ], "nullable": true }, "comparisons": { "default": null, "maxItems": 5, "description": "A list of up to 5 Comparisons, each containing 'name' and 'filters' properties. The 'filters' are the same structure as those in report.filters.", "type": "array", "items": { "$ref": "#/components/schemas/ReportComparison" }, "nullable": true } }, "required": [ "columns", "dataset_id", "property_ids", "title" ] } }, "responses": { "BAD_REQUEST": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "paths": { "/datainsights/v1.1/reports/query/export": { "post": { "parameters": [ { "in": "query", "name": "view", "required": true, "description": "View: should be either 'formatted' or 'details'", "schema": { "type": "string", "enum": [ "details", "formatted" ], "example": "details" } }, { "in": "query", "name": "format", "required": true, "description": "Format: should be either 'xlsx', 'csv' or 'json'", "schema": { "type": "string", "enum": [ "xlsx", "csv", "json" ], "example": "xlsx" } }, { "in": "query", "name": "include_charts", "required": false, "description": "Flag to include charts in the export, defaults to True", "schema": { "type": "boolean", "default": true, "example": true } }, { "in": "header", "name": "X-PROPERTY-ID", "required": true, "description": "Property id of the client", "schema": { "type": "integer", "writeOnly": true, "minimum": 1 } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportExport" } } } }, "400": { "$ref": "#/components/responses/BAD_REQUEST" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReportQueryExport" } } } }, "summary": "Query report data and export to file", "description": "Request a file export of data from any report json that is not created\n\nQuery report data from a report that is not created\n\nBased on the report `type` sent in the request, the data structure returned may have multiple formats.\n\nMode:\n- Export: 100000 Records\n\n## Types\n#### List\n```\n{\n ...\n \"columns\": ...\n \"settings\": {\n ...\n \"totals\": false,\n \"transpose\": false,\n }\n}\n```\n\n#### List (Totals)\n```\n{\n ...\n \"columns\": ...\n \"settings\": {\n ...\n \"totals\": true,\n \"transpose\": false,\n\n }\n}\n```\n#### PeriodList\n```\n{\n ...\n \"columns\": ...\n \"periods\": ...\n \"settings\": {\n ...\n \"totals\": false,\n \"transpose\": true|false,\n }\n}\n```\n\n\n#### Summary\n```\n{\n ...\n \"columns\": ...\n \"group_rows\": ...\n \"settings\": {\n ...\n \"totals\": false,\n \"transpose\": true|false,\n\n }\n}\n```\n\n#### Summary (Totals)\n```\n{\n ...\n \"columns\": ...\n \"group_rows\": ...\n \"settings\": {\n ...\n \"totals\": true\n \"transpose: true|false,\n }\n}\n```\n#### PeriodSummary\n```\n{\n ...\n \"columns\": ...\n \"group_rows\": ...\n \"periods\": ...\n \"settings\": {\n ...\n \"totals\": false,\n \"transpose\": true|false,\n }\n}\n```\n\n\n#### Pivot\n```\n{\n ...\n \"columns\": ...\n \"group_rows\": ...\n \"group_columns\": ...\n \"settings\": {\n ...\n \"totals\": false,\n \"transpose\": true|false\n }\n}\n```\n\n#### Pivot (Totals)\n```\n{\n ...\n \"columns\": ...\n \"group_rows\": ...\n \"group_columns\": ...\n \"settings\": {\n ...\n \"totals\": true,\n \"transpose\": true|false,\n }\n}\n```\n\n## Data\n\n| Type | Headers | Index | Records | Group Rows | Group Columns | Totals | Periods | Transpose |\n| -------------------- | ------- | ------ | ------- | ---------- | ------------- | ------ | ------- | --------- |\n| **List** | Yes | No | Yes | No | No | No | No | No |\n| **List (Totals)** | Yes | No | Yes | No | No | Yes | No | No |\n| **PeriodList** | Yes | Yes | Yes | No | No | No | Yes | Yes |\n| **Summary** | Yes | Yes | Yes | Yes | No | No | No | Yes |\n| **Summary (Details)** | Yes | Yes | Yes | Yes | No | Yes | No | No |\n| **Summary (Totals)** | Yes | Yes | Yes | Yes | No | Yes | No | Yes |\n| **PeriodSummary** | Yes | Yes | Yes | Yes | No | No | Yes | Yes |\n| **Pivot** | Yes | Yes | Yes | Yes | Yes | No | No | Yes |\n| **Pivot (Totals)** | Yes | Yes | Yes | Yes | Yes | Yes | No | Yes |", "tags": [ "Reports" ], "security": [ { "Authorization": [] } ] } } }, "tags": [ { "name": "Reports", "description": "Operations on reports" } ], "openapi": "3.0.2", "x-readme": { "explorer-enabled": true, "proxy-enabled": true } } ````