Cube.js REST API
Official vendor OpenAPI document · agent-readyAnalyticsBusiness Intelligencebearer2 EndpointsREST
For Agents
Run aggregated analytical queries against a Cube semantic layer and read the data model so an AI agent can answer business questions over a warehouse without writing SQL.
Use for: I want to query monthly revenue from our Cube deployment, Get the data model schema for my Cube deployment, Retrieve the list of available measures and dimensions, Run a Cube JSON query for orders grouped by status
Not supported: Does not handle data model definition, ingestion, or warehouse provisioning - use for executing Cube JSON queries and reading model metadata only.
The Cube.js REST API exposes a deployed Cube semantic layer over a customer's data warehouse, returning analytical query results and metadata about the available data model. The /v1/load endpoint accepts a Cube JSON query describing measures, dimensions, time dimensions, filters, and segments, and returns the aggregated rows along with the SQL that was generated. The /v1/meta endpoint returns the cubes, measures, dimensions, and segments defined in the data model so a client can build query UIs or expose the model to an LLM. Authentication is via a JWT bearer token signed with the Cube deployment's API secret.
Install Jentic One Beta
Connect the Cube.js REST API to your agent
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Cube.js REST API, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
1
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcube.dev%2Fcube" | sh2
Step 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Fcube.dev%2Fcube" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
Capabilities
What an agent can do with Cube.js REST API.
Run aggregated analytical queries via POST /v1/load using a Cube JSON query body
Read the available cubes, measures, dimensions, and segments via GET /v1/meta
Filter results by time dimension granularity such as day, week, or month
Apply security context constraints by signing a JWT with the appropriate user claims
Power an AI text-to-analytics workflow that translates natural language into Cube JSON queries
Stream measures and dimensions metadata into a UI builder for self-serve analytics
Use Cases
Patterns agents use Cube.js REST API for, with concrete tasks.
★ Natural Language Analytics over a Warehouse
An analytics chatbot can use the /v1/meta endpoint to learn the customer's Cube data model and then construct a Cube JSON query and call /v1/load to answer business questions. Because Cube enforces measures, dimensions, and security context server-side, the agent cannot accidentally write a join that returns ungoverned data. Build it once and the same agent works across BigQuery, Snowflake, Postgres, and other warehouses behind Cube.
Call GET /v1/meta to fetch measures and dimensions, then POST /v1/load with a Cube JSON query for measures Orders.count grouped by Orders.status for the last 30 days.
Embedded Analytics Dashboards
A SaaS product can fetch the Cube data model with /v1/meta to render an interactive query builder and submit user-built queries via /v1/load. Cube's row-level security uses the JWT security context, so dashboards can be embedded per tenant without exposing other customers' data. Suitable for B2B products that want self-serve charts without building a SQL editor.
Sign a JWT with the tenant ID claim, call GET /v1/meta, render a chart configuration, then POST /v1/load with the user-selected measures and dimensions.
Scheduled Metric Reporting
A reporting agent can run a fixed set of Cube queries on a schedule and post results to Slack or email. Each metric is a single POST /v1/load call against a stable measure such as Revenue.total, so the agent only needs the Cube secret to sign a JWT and the metric definitions. Useful for executive digests where the metric set rarely changes.
Sign a JWT for a reporting role and POST /v1/load with measures Revenue.total grouped by week for the last quarter, then post the result to Slack.
AI Agent Integration via Jentic
An AI agent that needs to answer warehouse questions can discover the Cube REST API through Jentic and run /v1/meta and /v1/load without hand-writing the integration. Jentic stores the Cube API secret and the host of the deployment so the agent works across environments without touching credentials directly.
Use Jentic search for 'run an analytics query on a Cube semantic layer', load the /v1/load schema, and execute it with a Cube JSON query.
Key Endpoints
2 endpoints — the cube.
METHOD
PATH
DESCRIPTION
POST
/v1/load
Run a Cube JSON query and return aggregated rows
GET
/v1/meta
Return the data model metadata
POST
/v1/load
Run a Cube JSON query and return aggregated rows
GET
/v1/meta
Return the data model metadata
Why Jentic?
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Cube.js REST API by hand means minting a signed JWT from your API secret, resolving your own {host} deployment into the base URL, and handling retries around query execution yourself. Through Jentic you install once, import the Cube.js REST API from the API Directory, store the API secret once, and your agent calls it.
Permission scoping
Cube.js takes the query in the request body rather than an id in the URL path, so limit the agent to the operations it needs, such as reading model metadata from /v1/meta. You choose whether query execution on /v1/load is also in scope.
Credential isolation
Your Cube API secret is stored once, encrypted, by your own Jentic One instance, which mints a short-lived JWT per call and injects it at execution time. The raw secret never enters the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'run an analytics query on a Cube semantic layer', and Jentic returns the /v1/load and /v1/meta operations with their input schemas so the agent constructs the right Cube JSON query without browsing the reference docs.
Related APIs
Alternatives and complements available in the Jentic catalogue.
FAQs
Specific to using Cube.js REST API through Jentic.
What authentication does the Cube.js REST API use?
Cube uses a JWT bearer token signed with the deployment's API secret, sent in the Authorization header as Bearer <jwt>. Through Jentic the secret is stored encrypted in your Jentic One instance and Jentic mints a short-lived JWT per call so the raw secret never enters the agent's prompt.
Can I run a SQL query directly with the Cube.js REST API?
Not directly. The Cube REST API takes a Cube JSON query that references measures and dimensions defined in the semantic layer, and Cube generates and runs the SQL. Use POST /v1/load with measures, dimensions, timeDimensions, and filters in the body.
What are the rate limits for the Cube.js REST API?
Rate limits depend on the Cube Cloud plan or the resources of the self-hosted deployment, not on a fixed limit in the spec. Cube returns 429 if the deployment is overloaded, and you can use the security context to throttle per tenant.
How do I run an analytical query with the Cube.js REST API through Jentic?
Run pip install jentic, search Jentic for 'run an analytics query on a Cube semantic layer', load the schema for /v1/load, and execute it with a Cube JSON query body. Jentic signs the JWT against your stored Cube secret so the agent does not handle the secret directly.
How do I list available measures and dimensions?
Call GET /v1/meta. It returns each cube along with its measures, dimensions, segments, and time dimensions, which is what an AI agent needs to construct a valid /v1/load query body without inspecting the data model files.
Is the Cube.js REST API free?
Cube Core is open source and free to self-host, so the REST API is free in that deployment. Cube Cloud has paid tiers based on data volume and concurrency, with a free developer tier for evaluation.
Can I limit what my agent is allowed to do with the Cube.js REST API?
Yes. Because you run Jentic One yourself, your own rules decide which Cube.js operations and credentials the agent may use. Since the API takes its query in the request body rather than an id in the URL path, you can scope the agent to read-only model metadata via GET /v1/meta and decide separately whether running queries with POST /v1/load is in scope. The agent can only call the operations you have allowed, and it signs each request against your stored Cube secret without ever seeing it.
GET STARTED