Cube Planning Cube Data API
The data stored in a cube for a company, organized by their dimensions.
OpenAPI Specification
openapi: 3.0.3
info:
title: Cube Agents Cube Data API
version: 1.0.0 (1.0)
description: "#### General Description\nAn API to access underlying Cube functionality. These endpoints are the same endpoints\nthat support Cube's universal add-ons and a plethora of integrations meaning you'll be able to interact with your\nCube data in many powerful ways. Visit the API section of Cube's [Help Center](https://help.cubesoftware.com/hc/en-us/sections/18205290556180-Custom-Integrations)\nfor more usage guides on how you can use this API to integrate with Cube to accomplish various tasks!\n\n#### Versioning\nAll requests to the API require a version to be configured via an `Accept` Header. The value of this Header should look like this:\n```\nAccept: application/json; version=1.0\n```\nNote that the version number may differ depending on which version of the endpoint is needed.\n\n#### Response Structure\nThe general response structure of Cube's API endpoints will contain a `\"data\"` and `\"metadata\"` root level key:\n```json\n{\n \"data\": { ... object data or list of objects ... },\n \"metadata\": {\n \"status\": 200,\n \"message\": \"Potential message with additional context\",\n \"error\": false,\n \"code\": \"\"\n }\n}\n```\n\n#### Rate Limiting\nAll endpoints have a rate limit configured, most of them default to 5/s.\nWhen the rate limit is encountered, a 429 HTTP code will be returned.\n\n#### Error Handling\nIn the event an error occurs, the response will typically look like this:\n```json\n{\n \"data\": {},\n \"metadata\": {\n \"status\": 400,\n \"message\": \"Some error message\",\n \"error\": true,\n \"code\": \"SOME_ERROR_CODE\"\n }\n}\n```\n"
termsOfService: https://www.cubesoftware.com/terms-of-service
servers:
- url: https://api.cubesoftware.com
description: Cube API Production URL
tags:
- name: Cube Data
description: The data stored in a cube for a company, organized by their dimensions.
paths:
/cube/analyze:
post:
operationId: cube_analyze_create
description: "Analyzes a 2D array of data representing potential data for the cube\n and determines where the various dimensions are within that data.\n "
summary: Analyze Matrix For Dimensions
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CubeAnalyze'
examples:
MatrixExample:
value:
address: A1:C3
matrix:
- - null
- Q1-22
- '2022'
- - Operating Expenses
- '123.34'
- - Income Statement
- '0.02'
summary: Matrix Example
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CubeAnalyze'
multipart/form-data:
schema:
$ref: '#/components/schemas/CubeAnalyze'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Matrix'
examples:
FullExample:
value:
rows:
- dimensions:
- id: null
parent_id: 1
name: Operating Expenses
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 1
special_case_id: null
date: null
has_children: false
write_block_reason: null
metadata: null
- id: null
parent_id: 1
name: Income Statement
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 1
special_case_id: null
date: null
has_children: false
write_block_reason: null
metadata: null
tld:
id: 1
parent_id: null
name: Account
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 1
special_case_id: null
date: null
has_children: false
write_block_reason: null
metadata: null
address: A2:A3
columns:
- dimensions:
- id: null
parent_id: null
name: Q1-22
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 1
special_case_id: null
date: '2022-03-31'
has_children: false
write_block_reason: null
metadata: null
- id: null
parent_id: 10
name: '2022'
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 1
special_case_id: null
date: '2022-12-31'
has_children: false
write_block_reason: null
metadata: null
tld:
id: 10
parent_id: null
name: Time
active: true
status: ENABLED
type: BASIC
rollup_type: null
formula: null
write_protection: NONE
position: 1
special_case_id: null
date: null
has_children: false
write_block_reason: null
metadata: null
address: B1:C1
summary: Full Example
description: ''
/cube/export:
get:
operationId: cube_export_list
description: List all exports
summary: List all exports
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Cube Data
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/BusinessIntelligenceExport'
description: ''
post:
operationId: cube_export_create
description: Begin an export
summary: Begin an export
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessIntelligenceExport'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/BusinessIntelligenceExport'
multipart/form-data:
schema:
$ref: '#/components/schemas/BusinessIntelligenceExport'
security:
- OAuth2: []
- {}
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/BusinessIntelligenceExport'
description: ''
/cube/export/notification/stale-data:
get:
operationId: cube_export_notification_stale_data_retrieve
summary: Get stale data notification details
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Cube Data
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StaleBiDataNotification'
examples:
Paused:
value:
paused: true
paused_at: '2026-07-19T00:15:28+00:00'
NotPaused:
value:
paused: false
paused_at: null
summary: Not paused
description: ''
put:
operationId: cube_export_notification_stale_data_update
summary: Set stale data notification details
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
type: object
properties:
paused:
type: boolean
required:
- paused
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/StaleBiDataNotification'
examples:
Paused:
value:
paused: true
paused_at: '2026-07-19T00:15:28+00:00'
NotPaused:
value:
paused: false
paused_at: null
summary: Not paused
description: ''
/cube/export/schedule:
get:
operationId: cube_export_schedule_list
description: Retrieve a BI data export schedule
summary: Retrieve a BI data export schedule
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Cube Data
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/ScheduledDataExport'
description: ''
post:
operationId: cube_export_schedule_create
description: Create a BI data export schedule
summary: Create a BI data export schedule
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledDataExport'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/ScheduledDataExport'
multipart/form-data:
schema:
$ref: '#/components/schemas/ScheduledDataExport'
security:
- OAuth2: []
- {}
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledDataExport'
description: ''
/cube/export/schedule/{id}:
patch:
operationId: cube_export_schedule_partial_update
description: Update a BI data export schedule
summary: Update a BI data export schedule
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PatchedScheduledDataExport'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/PatchedScheduledDataExport'
multipart/form-data:
schema:
$ref: '#/components/schemas/PatchedScheduledDataExport'
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ScheduledDataExport'
description: ''
delete:
operationId: cube_export_schedule_destroy
description: Delete a BI data export schedule
summary: Delete a BI data export schedule
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: Associates request with company
required: true
- in: path
name: id
schema:
type: string
required: true
tags:
- Cube Data
security:
- OAuth2: []
- {}
responses:
'204':
description: No response body
/cube/pivot:
post:
operationId: cube_pivot_create
description: 'This endpoint retrieves values stored in the OLAP cube for a given company. Any record with a null ID is a calculated value (i.e. rollups) whereas records with IDs are values explicitly stored in the cube.
This endpoint is useful when creating reports out of data in the cube. Like a pivot table, you are able to specify which dimensions are in your rows / columns for the report, and the API will figure out the appropriate data to pull. In the example on the right, the "Account" dimension is provided as rows with "Scenario" and "Time" being provided as columns. Therefore, the "Department" dimension must be provided as a filter.
You are able to pass either the names of the dimensions or their IDs as parameters.'
summary: Get Cube Values
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: The ID of the company that is making the request if the authenticated user has access to numerous companies
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CubePivot'
examples:
Row&ColumnExample:
value:
filters:
Department: Consolidated Only
rows:
- - Revenue
- COGS
columns:
- - Budget
- Actuals
- Budget
- Actuals
- - Jan-19
- Jan-19
- Feb-19
- Feb-19
summary: Row & Column Example
MatrixExample:
value:
filters:
Department: Consolidated Only
Scenario: Budget
matrix:
- - null
- Jan-19
- Feb-19
- Mar-19
- Q1-19
- - Meetings & Conferences
- null
- null
- null
- null
- - Legal Fees
- null
- null
- null
- null
- - Operating Expenses
- null
- null
- null
- null
- - Income Statement
- null
- null
- null
- null
summary: Matrix Example
RelativeDateExample:
value:
filters:
Department: Consolidated Only
Scenario: Actuals
Time: last month
rows:
- - Revenue
- COGS
columns:
- - last month
- this month
- this month T3M
- Last 3 Months
summary: Relative Date Example
description: 'Time dimensions support relative date phrases like "last month", "this month", "current quarter", "last year", etc. These can be used in rows, columns, or filters. Natural language time aggregations are also supported: "Last 3 Months", "Next 4 Months", "Last 2 Years", "Next 3 Quarters", and their exclusive variants.'
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CubePivot'
multipart/form-data:
schema:
$ref: '#/components/schemas/CubePivot'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CubePivotResponse'
examples:
FullExample:
value:
- id: 07c991586dfd4593add48225d06352b6
value: '1.00'
dimensions:
Account:
- id: 5192
name: Income Statement
active: true
status: ENABLED
- id: 5693
name: Revenue
active: true
status: ENABLED
- id: 5695
name: Product Revenue
active: true
status: ENABLED
Scenario:
- id: 5196
name: Actuals
active: true
status: ENABLED
Time:
- id: 5217
name: '2019'
active: true
status: ENABLED
- id: 5218
name: Q1-20
active: true
status: ENABLED
- id: 5219
name: Jan-20
active: true
status: ENABLED
Department:
- id: 5194
name: Consolidated Only
active: true
status: ENABLED
- id: null
value: '3.00'
dimensions:
Account:
- id: 5192
name: Income Statement
active: true
status: ENABLED
- id: 5700
name: Gross Revenue
active: true
status: ENABLED
Scenario:
- id: 5196
name: Actuals
active: true
status: ENABLED
Time:
- id: 5217
name: '2019'
active: true
status: ENABLED
- id: 5218
name: Q1
active: true
status: ENABLED
- id: 5221
name: March
active: true
status: ENABLED
Department:
- id: 5194
name: Consolidated Only
active: true
status: ENABLED
summary: Full Example
description: ''
/cube/pivot/sources:
post:
operationId: cube_pivot_sources_create
description: This endpoint retrieves the data sources powering the cube values for requested cross-sections.The full Source DataTable and ERP Connection details are provided, including the status of most recent import.
summary: Get Cube Value Sources
parameters:
- in: header
name: X-Company-ID
schema:
type: string
description: The ID of the company that is making the request if the authenticated user has access to numerous companies
required: true
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CubePivotSources'
examples:
MatrixExample:
value:
filters:
Department: All Departments
Scenario: Budget
Entity: All Entities
matrix:
- - null
- Jan-25
- Feb-25
- Mar-25
- Q2-25
- - Meetings & Conferences
- null
- null
- null
- null
- null
- - Legal Fees
- null
- null
- null
- null
- null
- - Operating Expenses
- null
- null
- null
- null
- null
- - Income Statement
- null
- null
- null
- null
- null
summary: Matrix Example
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CubePivotSources'
multipart/form-data:
schema:
$ref: '#/components/schemas/CubePivotSources'
required: true
security:
- OAuth2: []
- {}
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CubePivotSourceResponse'
description: The data table object
/cube/update:
post:
operationId: cube_update_create
description: This endpoint can be used to update data in the OLAP cube. The message will be used in the changelog for any changes to data. The raw data of the matrix as well as the filters should be passed. The data for `matrix.data` should be a 2D array of data similar to a spreadsheet. At least one row and one column of dimension names should be provided. The data in `matrix.filters` would contain values for any top level dimension that isn't a part of the passed 2D data matrix.
summary: Update Cube Values
parameters:
- in: query
name: background
schema:
type: boolean
description: Pass `true` to force the `DATA_UPDATE_BACKGROUNDED` behavior.
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CubeUpdateRequest'
examples:
ValuesAsStringsExample:
value:
message: A message for this change
matrix:
filters:
Department: 5345
Scenario: 345
data:
- - null
- Jan-19
- Feb-19
- Mar-19
- Q1-19
- - Meetings & Conferences
- 1
- 2
- 3
- 6
- - Legal Fees
- 11
- 22
- 33
- 66
- - Operating Expenses
- 12
- 24
- 36
- 72
- - Income Statement
- null
- null
- null
- null
summary: Values as Strings Example
ValuesAsDictionariesExample:
value:
message: A message for this change
matrix:
filters:
Department: 5345
Scenario: 345
data:
- - {}
- value: Jan-19
date: '2019-01-31 00:00:00'
- value: Feb-19
date: '2019-02-28 00:00:00'
- value: Mar-19
date: '2019-03-31 00:00:00'
- - value: Meetings & Conferences
- value: 1
- value: 2
- value: 3
summary: Values as Dictionaries Example
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CubeUpdateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/CubeUpdateRequest'
required: true
security:
- OAuth2: []
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/CubeUpdateResponse'
description: '`DATA_UPDATED` - Data was successfully updated as part of this request
`NO_DATA_UPDATED` - The request was successful, but no data was modified by it
`DATA_UPDATE_BACKGROUNDED` - Due to the amount of data sent, it will be processed in the background'
/cube/update_batch:
post:
operationId: cube_update_batch_create
description: Submit multiple matrix publishes in one request. Batch-level `message`, `currency`, and `metadata` apply to the whole run; each element of `publishes` contains a `matrix` (and optional per-publish `metadata`). Publishes are processed in order in the background. A batch may contain at most 50 publishes. Overlapping subcubes between any two publishes are rejected with 400. Optional per-publish `metadata.Range` sets the range label in the completion email (same key family as Document, Sheet, Software, URL, Publish Currency, Range); otherwise the server uses `Range {index}`.
summary: Update Cube Values (batch)
tags:
- Cube Data
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CubeBatchUpdateRequest'
examples:
BatchPublishExample:
value:
message: Changelog for the whole batch
currency:
code: USD
publishes:
- matrix:
filters:
Department: 5345
Scenario: 345
data:
- - null
- Jan-19
- Feb-19
- - Meetings & Conferences
- 1
- 2
metadata:
Range: Revenue by department
- matrix:
filters:
Department: 5346
Scenario: 345
data:
- - null
- Jan-19
- Feb-19
- - Travel
- 10
- 20
metadata:
Range: Travel detail
summary: Batch publish example
application/x-www-form-urlencoded:
schema:
$ref: '#/components/schemas/CubeBatchUpdateRequest'
multipart/form-data:
schema:
$ref: '#/components/schemas/CubeBatchUpdateRequest'
required: true
security:
- OAuth2: []
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/CubeBatchDataResponse'
description: Batch accepted for asynchronous processing. `backgrounding_info` includes `batch_id` and `publish_count`.
'400':
description: 'Validation failed. Possible error codes:
`BATCH_SUBCUBE_INTERSECTION` - Two or more publishes overlap in the cube. `meta.conflicting_ranges` lists the offending publishes.
`BATCH_PUBLISH_COUNT_EXCEEDED` - Batch contains more than 50 publishes. `meta.limit` and `meta.count` carry the configured maximum and the submitted count.'
components:
schemas:
OlapCubeChange:
type: object
properties:
id:
type: integer
readOnly: true
message:
type: string
nullable: true
maxLength: 1024
created_at:
type: string
format: date-time
readOnly: true
metadata:
nullable: true
type:
$ref: '#/components/schemas/OlapCubeChangeTypeEnum'
friendly_type:
type: string
readOnly: true
created_by:
$ref: '#/components/schemas/User'
user:
allOf:
- $ref: '#/components/schemas/User'
readOnly: true
num_changes:
type: integer
maximum: 4294967295
minimum: 0
format: int64
nullable: true
url:
type: string
readOnly: true
status:
$ref: '#/components/schemas/OlapCubeChangeStatusEnum'
batch_id:
type: string
readOnly: true
nullable: true
required:
- batch_id
- created_at
- created_by
- friendly_type
- id
- url
- user
Integration:
type: object
properties:
id:
type: integer
readOnly: true
source:
$ref: '#/components/schemas/IntegrationSourceEnum'
category:
$ref: '#/components/schemas/CategoryEnum'
name:
type: string
maxLength: 100
logo_url:
type: string
nullable: true
readOnly: true
required:
- category
- id
- logo_url
- name
- source
CubeUpdateResponse:
type: object
properties:
code:
type: string
message:
type: string
change:
$ref: '#/components/schemas/CubeUpdateResponseChange'
nonwriteable_dimensions:
$ref: '#/components/schemas/CubeUpdateResponseNonwriteableDimensions'
required:
- change
- code
- message
- nonwriteable_dimensions
CubePivot:
ty
# --- truncated at 32 KB (84 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/cube-planning/refs/heads/main/openapi/cube-planning-cube-data-api-openapi.yml