Close



Data Sources



General

Data Sources | General

Fields & Formulas

Data Sources | Fields & Formulas

Connections

Data Sources | Connections

Reports



Creating & Sharing

Reports | Creating & Sharing

Report Editing

Reports | Editing

Report Config

Reports | Report Config

Chart Cards

Reports | Chart Cards

Content Cards

Reports | Content Cards

Data Chat



General

Data Chat | General

AI Visibility



General

AI Visibility | General



General

AI | General

MCP (Model Context Protocol)

AI | MCP (Model Context Protocol)

Clients



General

Clients | General

Integrations



General

Integrations | General

Webhook — Local & Reviews

Integrations | Webhook — Local & Reviews

Webhook — Automation Payloads

Integrations | Webhook — Automation Payloads

Webhook — Other

Integrations | Webhook — Other

Settings



Account & Billing

Settings | Account & Billing

Users

Settings | Users

Comments & Notes

Settings | Comments & Notes

Notifications

Settings | Notifications

FAQ

Settings | FAQ

Other

Settings | Other

KPI Forecasting



General

KPI Forecasting | General

Settings & Status

KPI Forecasting | Settings & Status

Seasonality

KPI Forecasting | Seasonality

Metrics by Source

KPI Forecasting | Metrics by Source

Budget Tracking



General

Budget Tracking | General

Anomaly Detection



General

Anomaly Detection | General

Automation Jobs



General

Automation Jobs | General

Change History

Automation Jobs | Change History

URL & Page Checkers

Automation Jobs | URL & Page Checkers

Local & Reviews

Automation Jobs | Local & Reviews

Search Console

Automation Jobs | Search Console

Insights



Managing Insights

Insights | Managing Insights

Change History

Insights | Change History

URL & Page

Insights | URL & Page

Local & Reviews

Insights | Local & Reviews

Other Insight Types

Insights | Other Insight Types

Local Listings



General

Local Listings | General

Profiles & Content

Local Listings | Profiles & Content

Performance & Activity

Local Listings | Performance & Activity

Media

Local Listings | Media

Categories & Services

Local Listings | Categories & Services

Reviews



General

Reviews | General

General

Social Posts | General

Creating Posts

Social Posts | Creating Posts

Managing Posts

Social Posts | Managing Posts

Data Warehouse



Pipelines

Data Warehouse | Pipelines

Access & Credits

Data Warehouse | Access & Credits

Source Fields

Data Warehouse | Source Fields

Data Studio

Data Warehouse | Data Studio

BigQuery

Data Warehouse | BigQuery

General

Clients | General

General

Integrations | General

MCP

Integrations | MCP

Webhook — Automation Payloads

Integrations | Webhook — Automation Payloads

Webhook — Local & Reviews

Integrations | Webhook — Local & Reviews

Webhook — Other

Integrations | Webhook — Other

Account & Billing

Settings | Account & Billing

Users

Settings | Users

Comments & Notes

Settings | Comments & Notes

Notifications

Settings | Notifications

FAQ

Settings | FAQ

Other

Settings | Other

Recent Updates



Account Settings

Settings | Account & Billing

Acknowledging and Resolving Insights

Insights | Managing Insights

Add comment from Slack

Integrations | General

Add comment from Zapier

Settings | Comments & Notes

Adding a User

Settings | Users

AI Analysis Generation

Reports | Creating & Sharing

AI Credits

AI | General

AI Models

AI | General

AI Visibility Insights

AI Visibility | General

AI Visibility Overview

AI Visibility | General

AI Visibility Settings

AI Visibility | General

AI Visibility Webhook Payload

Integrations | Webhook — Other

Analysis Card

Reports | Content Cards

Anomalies Bulk Action

Anomaly Detection | General

Anomaly Algorithm

Anomaly Detection | General

Anomaly Detection

Anomaly Detection | General

Anomaly Detection Insight

Insights | Other Insight Types

Anomaly Detection Settings

Anomaly Detection | General

Anomaly Detection Webhook Payload

Integrations | Webhook — Other

Anomaly Job Common Errors

Anomaly Detection | General

An overview of Local Listings

Local Listings | General

An overview of Reviews

Reviews | General

Answers

AI Visibility | General

Area Chart Card

Reports | Chart Cards

Attributes

Local Listings | Profiles & Content

Automatic Schema Updates

Data Warehouse | Pipelines

Automation: Facebook Ads Destination URL Checker

Integrations | Webhook — Automation Payloads

Automation: Google Ads Change History

Integrations | Webhook — Automation Payloads

Automation: Google Ads Destination URL Checker

Integrations | Webhook — Automation Payloads

Automation: Google Analytics Change History

Integrations | Webhook — Automation Payloads

Automation: Google Business Profile Answer

Integrations | Webhook — Local & Reviews

Automation: Google Business Profile Change History

Integrations | Webhook — Automation Payloads

Automation: Google Business Profile Pending Updates

Integrations | Webhook — Local & Reviews

Automation: Google Business Profile Question

Integrations | Webhook — Local & Reviews

Automation: Google Review

Integrations | Webhook — Local & Reviews

Automation: Google Review Change History

Integrations | Webhook — Automation Payloads

Automation Job Common Errors

Automation Jobs | General

Automation Jobs

Automation Jobs | General

Automation: Microsoft Ads Destination URL Checker

Integrations | Webhook — Automation Payloads

Automation: Page Status Checker

Integrations | Webhook — Automation Payloads

Automation: Robots.txt Change Detection

Integrations | Webhook — Automation Payloads

Automations Bulk Action

Automation Jobs | General

Automation: Search Console Activity

Integrations | Webhook — Automation Payloads

Automation: Search Console Keyword Movement

Integrations | Webhook — Automation Payloads

Auto Resolving

Insights | Managing Insights

Bar Chart Card

Reports | Chart Cards

Branding

Reports | Creating & Sharing

Budget Campaign Dynamic Filter

Budget Tracking | General

Budget Common Errors

Budget Tracking | General

Budget history

Budget Tracking | General

Budgets Bulk Actions

Budget Tracking | General

Budget Settings

Budget Tracking | General

Budget Status

Budget Tracking | General

Budget Tracker Webhook Payload

Integrations | Webhook — Other

Budget Tracking

Budget Tracking | General

Budget Webhook URL

Budget Tracking | General

Build Reports with Jepto MCP

AI | MCP (Model Context Protocol)

Bulk Action

Local Listings | General

Bulk Upload Images

Local Listings | Media

Calendar

Social Posts | General

Cancel Subscription

Settings | Account & Billing

Card Chat

Reports | Editing

Card Data Filters

Reports | Creating & Sharing

Data Query

‍
‍

A data query is how you request data from any source connected to Jepto. You describe what you want in one JSON format: fields from the Data Model, a date range, filters and a sort order. Jepto fetches from Google Ads, GA4, Meta, BigQuery or any other connected platform and returns rows keyed by the same field names. You don’t call each platform’s API, handle its authentication or reconcile its formats.

Send queries from your own systems and agents through Jepto MCP. The same format also powers every report card and Data Chat answer in Jepto, so your numbers match the product’s.

Request

{
  "measures": ["unified.spend"],
  "dimensions": ["unified.source"],
  "timeDimensions": [{
    "dimension": "unified.date",
    "dateRange": ["lastMonth"]
  }]
}

Jepto

Checks fields against your Data Model
Expands custom fields into their formulas
Fetches each platform, or serves from cache
Combines the sources and aggregates

Response

{
  "data": [
    { "unified.source": "googleAds",
      "unified.spend": 21400 },
    { "unified.source": "facebookAds",
      "unified.spend": 15320 }
  ]
}

Request and response

The format isn’t proprietary. It follows the query conventions of Cube, the open-source semantic layer: measures, dimensions, time dimensions and filters.

Open standard

Documented in public

The conventions are open source and documented in the Cube query format, so your team isn’t learning a format that only works with Jepto.

AI-ready

AI tools already know it

Cube has been public since 2019, so AI coding assistants and agents have seen the format for years. They write valid queries with little prompting.

Portable

Skills and code carry over

Anyone who has used a semantic layer will recognise it straight away, and the code your team writes stays readable outside Jepto.

Where Jepto adds to it: measureAggregations for rollup overrides, compact relative date tokens such as last30days, a previous-period form of compareDateRange, and custom_… fields that Jepto calculates for you. The rest follows Cube’s conventions.

Here’s Google Ads spend by campaign for the last 30 days, Brand campaigns only, highest spend first:

RequestJepto MCP · Data Chat · Reports

{
  "measures": ["googleAds.spend"],
  "measureAggregations": { "googleAds.spend": "sum" },
  "dimensions": ["googleAds.campaignName"],
  "timeDimensions": [
    { "dimension": "googleAds.date", "dateRange": ["last30days"] }
  ],
  "filters": [
    { "member": "googleAds.campaignName", "operator": "contains", "values": ["Brand"] }
  ],
  "order": { "googleAds.spend": "desc" },
  "limit": 100,
  "total": true
}

ResponseRow keys match the fields you asked for

{
  "data": [
    { "googleAds.campaignName": "Brand | Search", "googleAds.spend": 1840.5 },
    { "googleAds.campaignName": "Brand | PMax", "googleAds.spend": 962.1 }
  ],
  "total": 2
}

Query reference

Key	Type	What it does
`measures`	string[]	Metrics to return, for example `googleAds.spend` or a custom field such as `custom_be764589f064fe7b`
`measureAggregations`	object	Optional override of how a metric rolls up: `sum`, `avg`, `min`, `max`, `count`, `count_distinct`. Each field already has a default.
`dimensions`	string[]	Fields to group by, for example `googleAds.campaignName`
`timeDimensions`	array	`{ dimension, dateRange, granularity? }`. The date field, the period and optional day, week, month, quarter or year buckets.
`filters`	array	`{ member, operator, values }`. Every filter must pass. See Filters.
`order`	object	`{ "field": "asc" \| "desc" }`
`limit`, `offset`	number	Page through large results
`total`	boolean	Also return the total row count before `limit`, for pagination
`timezone`	string	IANA time zone used to resolve dates, for example `Australia/Sydney`

There’s no “source” key. Every field key starts with its platform (googleAds., facebookAds., unified.), and Jepto routes each part of the query from that. To find the keys available for a client, see the Data Model, or call analytics_schema over MCP.

‍

Query from your own systems

Connect any MCP-capable client, agent framework or internal tool to https://mcp.jepto.com. It signs in with your Jepto account over OAuth and can then query every client that login can see.

client_listGet the clientId

datasource_listSee what’s connected

analytics_schemaList fields, including custom fields

analytics_queryRun the query, get rows

analytics_query takes measures, dimensions, filters, order, limit, offset and timezone exactly as above. Dates are passed as dateRange (or startDate and endDate) plus granularity. Setup is covered in Jepto MCP Server Overview and OAuth & Authentication.

Because your systems read the same Data Model as Jepto, custom metrics you define once (such as blended ROAS or spend after fees) come back already calculated. Numbers also match what the same query shows in a Jepto report.

‍

Dates and granularity

A date range has a start and an end. Each can be an ISO date (2026-01-01) or a relative token that is recalculated every time the query runs:

Type	Tokens
Single days	`today` `yesterday`
Period to date	`thisWeek` `thisMonth` `thisYear`
Completed periods	`lastWeek` `lastMonth` `lastYear`
Rolling windows	`last7days` `last30days` `last90days`, or any `lastNdays`
Offsets	`7DaysAgo` `4WeeksAgo` `3MonthsAgo` `2QuartersAgo` `2YearsAgo`

Combine tokens for custom windows. For example, ["30DaysAgo", "yesterday"] gives the last 30 complete days.

Without granularity, you get one aggregated row per dimension value for the whole range. Use this for tables and totals.
With granularity (day, week, month, quarter, year), you get a row per bucket as well. 90 days at week returns about 13 rows per dimension value.

‍

Filters

Each filter is a field (member), an operator and values. The operators you can use depend on the field:

Text dimensions

equalsnotEqualscontainsnotContainsstartsWithendsWithsetnotSet

Metrics

equalsnotEqualsgtgteltltesetnotSet

Dates

inDateRangenotInDateRangebeforeDateafterDate

‍

Comparing periods

To compare two periods, replace dateRange with compareDateRange. The same query runs for both periods:

Previous period30 days compared with the 30 days before

{ "dimension": "googleAds.date",
  "compareDateRange": {
    "providedDateRange": ["2026-08-16", "2026-09-14"],
    "previousPeriod": ["2026-07-17", "2026-08-15"]
  } }

Previous yearSame days, twelve months earlier

{ "dimension": "googleAds.date",
  "compareDateRange": [["2026-08-16", "2026-09-14"], ["2025-08-16", "2025-09-14"]] }

‍

Querying more than one source

Jepto splits the query by platform prefix, fetches each platform separately, stacks the rows (a union, not a join) and then aggregates.
Use unified fields (unified.spend, unified.clicks) to compare platforms in one query. Each maps to the matching field on every platform. Add unified.source as a dimension to label each row with its platform.
An unmapped platform returns nothing for that field. Meta has no unified conversions, conversion value or ROAS. The full mapping is in Unified Fields.
Filter on fields that exist on every source in the query.
Custom fields are calculated by Jepto. Request custom_… keys like any other field; you never send the formula.

‍

Results and caching

Identical queries return identical numbers, whether they come from your system, Data Chat or a report card. If two results disagree, their queries differ.
Recent results are cached, so repeat queries return quickly. Queries are recalculated rather than stored, so relative dates like last30days always resolve to today’s window.

‍

Inside Jepto: the query behind every card

Every chart and table card in Jepto is a saved data query. The card’s Data tab builds the query, and the preview pane’s Data Query tab shows the exact request, in the same format as above. It’s the quickest way to copy a working query into your own system.

Data tab settingQuery keyWhat it decides

Data to Displaymeasures measureAggregations

What to measure, and how each metric rolls up

Dimension, Breakdowndimensions

What to break the numbers down by

Date Range, GranularitytimeDimensions

Which period, and whether to split it by day, week or month

Filtersfilters

Which rows to include or leave out

ComparisoncompareDateRange

A second period to compare against

Sort By, Order, Rows per pageorder limit

Row order, and how many rows a table shows

Use Default Date Range: leave it on for most cards so they follow the report’s date picker. Turn it off only when a card needs a fixed window, such as a launch period.

Report filters stack in three layers

In a report, a card’s final rows must pass every layer that applies to it:

Layer 1Card filtersAlways applied. Use them for permanent definitions, such as “Brand campaigns only”.

Layer 2 · andPage filtersDate range and dropdown filter cards that viewers can change

Layer 3 · andReport date rangeOnly for cards with Use Default Date Range on

Rows shownOnly rows that pass every layer

If a card ignores a page filter, check three things: the filter targets this card, the field exists on this card’s sources, and not every option is selected. A dropdown with everything selected counts as no filter and is left out of the query.

Letting AI draft it: Card Chat builds the query from a sentence such as “Line chart of spend and clicks by day, last 30 days, Google Ads and Meta”. Check the Data tab before saving.

‍

Troubleshooting

Problem	Likely cause	Fix
Empty result	Filters too tight, no data in the range, or the source isn’t connected for this client	Loosen filters, widen the range, check `datasource_list`
Unknown field error	Wrong casing or a field not available to this client	Copy keys exactly from `analytics_schema` or the Data Model (`googleAds.campaignName`, not `campaign_name`)
One row per day instead of totals	`granularity` is set	Remove `granularity` from the time dimension
One source returns zero	The unified field isn’t mapped for that platform	Use that platform’s own field
Your number differs from a Jepto report	The queries differ in fields, filters, dates or time zone	Open the card’s Data Query tab and compare it with your request
Report card shows wrong dates	Use Default Date Range is off	Turn it on
Report page dropdown does nothing	It doesn’t target this card, every option is selected, or the field isn’t on this card’s sources	Check the targets, pick specific values, use a shared dimension

Was this article helpful?



Nice one!

Thanks a lot for your feedback! If you’d like a member of our support team to respond to you, please send a message here



Please try again

Oops! Something went wrong while submitting the form.



Nice one!

Thanks a lot for your feedback! If you’d like a member of our support team to respond to you, please send a message here



Please try again

Oops! Something went wrong while submitting the form.