Submit report and dataset queries, generate SQL without executing, and retrieve paginated query results from Holistics reports and the dataset semantic layer.
openapi: 3.0.1
info:
title: Holistics API
description: >-
REST API for the Holistics business intelligence and self-service analytics
platform. Covers the Data Pipeline API (execute data imports/transforms and
poll ETL jobs), report and dataset query APIs, and asynchronous data export
(CSV/JSON/XLSX). All requests authenticate with a per-user API key passed in
the X-Holistics-Key header. Regional hosts are secure.holistics.io (APAC),
us.holistics.io (US), and eu.holistics.io (EU).
termsOfService: https://www.holistics.io/terms/
contact:
name: Holistics Support
url: https://www.holistics.io
email: support@holistics.io
version: '2.0'
servers:
- url: https://secure.holistics.io/api/v2
description: APAC region
- url: https://us.holistics.io/api/v2
description: US region
- url: https://eu.holistics.io/api/v2
description: EU region
security:
- HolisticsKey: []
tags:
- name: Datasets
description: Query the Holistics dataset semantic layer.
- name: Reports
description: Submit report queries and retrieve results.
- name: Export
description: Asynchronous report data export jobs.
- name: Data Pipeline
description: Execute data imports and transforms.
- name: Jobs
description: Poll ETL and export job status.
paths:
/data_sets:
get:
operationId: listDataSets
tags:
- Datasets
summary: List available datasets
description: Returns the datasets the calling user can query.
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/DataSet'
/data_sets/{id}:
get:
operationId: getDataSet
tags:
- Datasets
summary: Get dataset dimensions and metrics
description: Returns the available dimensions and metrics for a dataset.
parameters:
- $ref: '#/components/parameters/PathId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/DataSetDetail'
/data_sets/{id}/submit_query:
post:
operationId: submitDataSetQuery
tags:
- Datasets
summary: Query a dataset
description: Executes a query against a dataset and returns result rows.
parameters:
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResult'
/data_sets/{id}/generate_sql:
post:
operationId: generateDataSetSql
tags:
- Datasets
summary: Generate SQL without executing
description: Returns the SQL that would be generated for a dataset query.
parameters:
- $ref: '#/components/parameters/PathId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueryRequest'
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
sql:
type: string
/queries/{report_id}/submit_query.json:
get:
operationId: submitReportQuery
tags:
- Reports
summary: Submit a report query job
description: >-
Submits a query job for a report. Filter values are passed as query
parameters. Returns a job id to poll for results.
parameters:
- $ref: '#/components/parameters/ReportId'
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobSubmitResponse'
/queries/get_query_results.json:
get:
operationId: getQueryResults
tags:
- Reports
summary: Retrieve report query results
description: Retrieves the paginated results of a submitted query job.
parameters:
- name: job_id
in: query
required: true
schema:
type: string
- name: _page_size
in: query
required: false
schema:
type: integer
- name: _page
in: query
required: false
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/QueryResult'
/queries/{report_id}/submit_export.{format}:
get:
operationId: submitReportExport
tags:
- Export
summary: Submit a report export job
description: >-
Submits an export job for a report in the given format. Filter values
are passed as query parameters. Returns an export job id.
parameters:
- $ref: '#/components/parameters/ReportId'
- name: format
in: path
required: true
schema:
type: string
enum:
- csv
- json
- xlsx
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobSubmitResponse'
/queries/get_export_results.json:
get:
operationId: getExportResults
tags:
- Export
summary: Retrieve export job status
description: Returns the status of a submitted export job.
parameters:
- name: job_id
in: query
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
/exports/download:
get:
operationId: downloadExport
tags:
- Export
summary: Download an export result file
description: >-
Downloads the exported file once the export job status is success.
parameters:
- name: job_id
in: query
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/octet-stream:
schema:
type: string
format: binary
/data_imports/{data_import_id}/execute.json:
post:
operationId: executeDataImport
tags:
- Data Pipeline
summary: Execute a data import job
description: Triggers execution of a Holistics data import.
parameters:
- name: data_import_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobSubmitResponse'
/data_transforms/{data_transform_id}/execute.json:
post:
operationId: executeDataTransform
tags:
- Data Pipeline
summary: Execute a data transform job
description: Triggers execution of a Holistics data transform.
parameters:
- name: data_transform_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/JobSubmitResponse'
/jobs/{job_id}/logs.json:
get:
operationId: getJobLogs
tags:
- Jobs
summary: View running job information
description: Returns logs and runtime information for a job.
parameters:
- name: job_id
in: path
required: true
schema:
type: string
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Job'
/jobs/last_run_jobs.json:
get:
operationId: getLastRunJobs
tags:
- Jobs
summary: Check status of recent ETL jobs
description: >-
Returns the most recent job for each requested data import or transform.
parameters:
- name: source_type
in: query
required: true
schema:
type: string
enum:
- DataImport
- DataTransform
- name: ids
in: query
required: true
description: Comma-separated list of import or transform IDs.
schema:
type: array
items:
type: integer
responses:
'200':
description: OK
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Job'
components:
securitySchemes:
HolisticsKey:
type: apiKey
in: header
name: X-Holistics-Key
description: Per-user API key generated from Holistics user settings.
parameters:
PathId:
name: id
in: path
required: true
schema:
type: integer
ReportId:
name: report_id
in: path
required: true
schema:
type: integer
schemas:
DataSet:
type: object
properties:
id:
type: integer
name:
type: string
title:
type: string
DataSetDetail:
type: object
properties:
id:
type: integer
name:
type: string
dimensions:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
metrics:
type: array
items:
type: object
properties:
name:
type: string
type:
type: string
QueryRequest:
type: object
properties:
dimensions:
type: array
description: Fields to group results by.
items:
type: string
metrics:
type: array
description: Aggregated measures to calculate.
items:
type: string
filters:
type: array
description: Conditions for filtering data.
items:
type: object
limit:
type: integer
description: Maximum number of rows returned.
QueryResult:
type: object
properties:
job_id:
type: string
status:
type: string
columns:
type: array
items:
type: string
data:
type: array
items:
type: array
items: {}
JobSubmitResponse:
type: object
properties:
job_id:
type: string
status:
type: string
Job:
type: object
properties:
id:
type: integer
status:
type: string
description: e.g. running, success, failed.
source_type:
type: string
start_time:
type: string
format: date-time
end_time:
type: string
format: date-time
created_at:
type: string
format: date-time