Omniscope Query API: accessing and tranforming data via REST

Modified on Mon, 3 Nov at 6:02 PM

The Query API is Omniscope's data access layer: it lets you query the data behind any report configured data source and receive results in structured JSON, so that other systems or applications can consume your datasets programmatically, no CSV exports required.

Whether you’re building a custom web app, embedding Omniscope data in another platform, or providing an API endpoint to a client, the Query API gives you full flexibility over what data to fetch, how to aggregate / transform it, and how to format the results.

Overview

Every Omniscope project and report exposes one or more queryable endpoints that can be called either:

From within Omniscope (e.g. a Custom View using JavaScript), or
From external systems, using standard REST calls with JSON request bodies.

Each endpoint is documented automatically in Swagger / OpenAPI format, allowing you to explore and test queries interactively.

Example:
? Query API Swagger sample
? Custom View API reference

Key Capabilities

Feature	Description
Tabular queries	Retrieve raw or aggregated data, similar to SQL `SELECT … GROUP BY`
Formula queries	Evaluate formulas server-side and return a scalar or small dataset
Batch queries	Execute multiple queries in a single call
Schema queries	Retrieve schema metadata (fields, types, formatting)
Filtering and sorting	Apply advanced filters and sorting conditions, similar to Omniscope filters
Pagination	Use `range.start` and `range.length` to fetch partial results
Aggregation functions	Record count, sum, average, min/max, and many others

Making a Query (REST)

To query Omniscope data from an external app:

1. Find the endpoint

Each report or data block exposes a Query API endpoint, e.g.:

https://your-omniscope-server/path/to/project/query/v1/table

The /meta/ variant (e.g. /query/v1/meta/) provides the Swagger docs for that project.

2. Send a POST request with a JSON query

Example request

POST https://your-server/path/to/project/query/v1/table 
{  "groupings": [    { "inputField": "Country", "type": "UNIQUE_VALUES", "name": "Country" }  ],  "measures": [    { "name": "Record count", "function": "RECORD_COUNT" }  ],  "filter": {    "type": "AND",    "filters": [      { "type": "FIELD_VALUE", "inputField": "Year", "operator": ">=", "value": 2020 }    ]  },  "sorts": [    { "inputField": "Record count", "direction": "DESCENDING" }  ],  "range": { "start": 0, "length": 100 } }

Example response

{  "schema": [    { "name": "Country", "type": "STRING" },    { "name": "Record count", "type": "NUMBER" }  ],  "records": [    ["UK", 1054],    ["US", 893],    ["Germany", 746]  ]
}

Using the Query API inside a Custom View (JavaScript)

Within Omniscope, the same API can be accessed through the JavaScript helper:

omniscope.query  .builder(omniscope.view.endpoint())  .table({    groupings: [],    measures: [{ function: "RECORD_COUNT" }]  })  .on("load", event => console.log(event.data.records))  .on("error", event => omniscope.view.error(event.data.message))  .execute();

This lets your custom visualisations dynamically retrieve filtered, aggregated, or raw data based on the current report context.

Available Query Methods

Method	Purpose
`table(query)`	Tabular data query (aggregations, filters, sorts)
`formula(query)`	Compute expressions, metrics, or KPIs
`batch(query)`	Run multiple sub-queries in one request
`schema()` / `schema(query)`	Retrieve schema for dataset or subset of fields

Each supports event callbacks (load, error, progress) in JavaScript, or direct HTTP status handling in REST.

Authentication and Access Control

The Query API respects Omniscope’s built-in project and report permissions and user authentication (OpenID, list-based, or anonymous).
Each dataset’s endpoint is only queryable if the calling user has “Viewer data” permission for that report or block.

Example Use Cases

Serve JSON to third-party systems instead of exporting CSVs
Build notification systems that query Omniscope data directly
Feed other services with live, filtered Omniscope data
Wrap Omniscope datasets in your own API layer to match client-specific schemas

Pro Tips

Use /meta endpoints to explore your server’s live Swagger docs and test queries.
Combine with Workflow API or Scheduler API if you want to trigger refresh and then query fresh data automatically.
For highly customised output you can wrap Query API responses in a Custom JS View or Python output block.

⚙️ Access Control and Security Considerations

Omniscope is designed to provide a consistent and transparent model of data access between reports and APIs.
Whenever a report is configured with one or more Sources in its Report Data Model → Sources section, those sources automatically become available via corresponding /query/v1/ endpoints.

This means the same data that powers the report’s visuals can also be queried programmatically through the Query API, by any user who already has permission to view the report.

Omniscope treats “report viewing access” and “data querying access” as the same permission level, ensuring consistency between what users see and what they can retrieve through the platform’s APIs.

There is no separate configuration to disable the Query API independently from report access.
The report’s data model defines what a viewer can query, not just what is displayed in the charts.

This approach is common among analytical platforms: viewing a report inherently grants access to the underlying dataset that powers it.

If a report viewer runs a Query API request, they may be able to extract the full dataset that underlies a visualisation, rather than just the aggregated values shown in a chart, as if they were adding a "Table view".
This is not a security flaw: it’s how Omniscope ensures predictable, uniform access to report data.

Best Practices for Data Governance

To ensure your reports only expose appropriate data, we recommend these standard practices:

1. Control who can view reports

Limit report access for sensitive datasets.
Treat “View report” permission as equivalent to granting API-level access to that report’s data model.

2. Publish curated or aggregated sources

In the Report Data Model, connect only derived or sanitised outputs from your workflow (aggregated, filtered, or anonymised).
Avoid linking raw workflow inputs directly to reports.

3. Separate internal and published projects

Keep raw or detailed data in internal projects with restricted access.
Use workflow outputs to feed viewer-facing reports containing only approved summaries.

4. Monitor and log API usage

Use server or proxy logs to monitor Query API traffic for auditing or compliance purposes.

5. Secure external deployments

When Omniscope is internet-facing, deploy it behind an authentication proxy (SSO, API gateway, or VPN).
Always enforce HTTPS and secure session management.

6. Control outputs explicitly

If needed, use workflow output blocks or custom scripts to publish controlled, aggregated datasets instead of exposing live report sources.

In Summary

Query API access is automatically available for any data source defined in a report’s Data Model.
There is no separate toggle to disable the API for authenticated report viewers.
Report access and data model access are equivalent by design — ensuring consistency between visual and programmatic access.
Secure design means publishing only data you’re comfortable exposing through the API as well as in visuals.

Administrator Note

Administrators should understand that view access to a report implies Query API access to its data model.
This is part of Omniscope’s unified data-access design and not a vulnerability.

For environments with sensitive or regulated data:

Create “viewer-safe” layers (aggregated or anonymised).
Apply strict access segregation between raw/ETL projects and published dashboards.
Optionally place Omniscope behind an authentication proxy when externally accessible.