canonical: https://jentic.com/apis/cube.dev/cube # Cube.js REST API 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. ## For AI 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. ## Scope Does not handle data model definition, ingestion, or warehouse provisioning - use for executing Cube JSON queries and reading model metadata only. ## Capabilities - 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 ### 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. Example prompt: 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. Example prompt: 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. Example prompt: 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. Example prompt: 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 | Method | Path | Description | | --- | --- | --- | | POST | `/v1/load` | Run a Cube JSON query and return aggregated rows | | GET | `/v1/meta` | Return the data model metadata | ## Key resources - **Data** — Run analytical queries via the Cube JSON query format. - **Metadata** — Inspect the cubes, measures, dimensions, and segments exposed by the deployment. ## Why Jentic - **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 handling:** 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. - **Discovery method:** 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 - **Snowflake API** — Snowflake is a common warehouse Cube reads from, exposed via Cube's measures and dimensions. - **Tableau REST API** — Tableau provides BI dashboards as an alternative to Cube's headless semantic layer. - **Metabase API** — Metabase exposes saved questions and dashboards over an API, overlapping with Cube's analytical query layer. ## FAQ ### 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 . 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.