Querying data

POST /v1/data/query returns live metric values from one of a client’s connected data sources. It’s the same call that powers every chart and KPI widget in the app, exposed for your own automations.

This endpoint proxies to Oviond’s datasource service. It reads a data source the client has already connected in the app — it does not create or authorize connections. Connect a source in the project editor first.

Request

curl -X POST https://api.oviond.com/v1/data/query \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "datasource_id": "ga4",
    "client_id": "cliAbc123",
    "date_range": { "current_start": "2026-03-01", "current_end": "2026-03-31" },
    "metrics": ["sessions", "conversions"],
    "dimensions": ["DATE"],
    "data_view": "OVERVIEW"
  }'

Field	Required	Description
`datasource_id`	✓	The datasource alias, e.g. `ga4`, `gadw`, `fb-ads`. List all with `GET /v1/datasources`.
`client_id`	✓	The client whose connected data source you’re querying. List with `GET /v1/clients`.
`date_range`	✓	`{ current_start, current_end }` as `YYYY-MM-DD`. Add `previous_start` / `previous_end` to get period-over-period comparison values.
`metrics`	✓	Array of metric `id`s, e.g. `["clicks", "impressions"]`. Get valid ids from `GET /v1/datasources/{datasource_id}/describe`.
`dimensions`	✓	Array of dimension `id`s, e.g. `["DATE"]` for a time series, or `[]` for a single total. Get valid ids from `GET /v1/datasources/{datasource_id}/describe`.
`data_view`	✓	The datasource view, e.g. `ACCOUNT`. A metric or dimension is only valid inside its own view — `/describe` groups them by view.
`filters`		Array of `{ field, operator, value }` filter objects. `operator` is one of `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `greater_than`, `less_than`, `greater_than_or_equal`, `less_than_or_equal`. Add `"logicalOperator": "and"` (or `"or"`) to combine multiple filters.
`timezone`		IANA timezone for date bucketing. Defaults to `UTC`.

Response

{
  "success": true,
  "data": {
    "current": [
      { "DATE": "2026-03-01", "sessions": 1240, "conversions": 18 },
      { "DATE": "2026-03-02", "sessions": 1310, "conversions": 22 }
    ],
    "currentSummary": { "sessions": 39120, "conversions": 604 },
    "previous": [],
    "previousSummary": {},
    "state": "ACTIVE"
  },
  "meta": { "request_id": "req_a1b2c3" }
}

data.current — the rows for the current range (one per dimensions bucket, keyed by your metric and dimension identifiers).
data.currentSummary — the totals across the current range.
data.previous / data.previousSummary — the same for the comparison period, when you pass previous_start / previous_end (empty otherwise).
data.state — ACTIVE when the connection returned data.

Read fields by the identifiers you requested rather than by position; the exact keys vary by datasource and data_view.

Finding valid identifiers

The valid datasource_id, metrics, dimensions, and data_view values are all discoverable — you never have to guess. Walk the field catalog: 1. Find the datasource_id — list every datasource Oviond supports:

curl "https://api.oviond.com/v1/datasources" \
  -H "Authorization: Bearer YOUR_API_KEY"
# → [{ "id": "gadw", "name": "Google Ads", "category": "...", "data_views": [...] }, ...]

2. Describe it — one call returns its data views and every field you can query:

curl "https://api.oviond.com/v1/datasources/gadw/describe" \
  -H "Authorization: Bearer YOUR_API_KEY"

{
  "success": true,
  "data": {
    "datasource_id": "gadw",
    "default_data_view": "ACCOUNT",
    "data_views": [
      { "value": "ACCOUNT", "label": "Account", "required_advanced": [] },
      { "value": "CAMPAIGNS", "label": "Campaigns", "required_advanced": [] }
    ],
    "metrics": [
      { "id": "impressions", "name": "Impressions", "data_view": "ACCOUNT", "group": "Basic" },
      { "id": "clicks", "name": "Clicks", "data_view": "ACCOUNT", "group": "Basic" }
    ],
    "dimensions": [
      { "id": "DATE", "name": "Date", "data_view": "TIME", "group": "Time" }
    ]
  }
}

Use each id as an entry in metrics / dimensions, and its data_view as data_view. Add ?data_view=ACCOUNT to scope the response to one view. Three things in the response decide what you can combine:

data_view — a metric or dimension is only valid inside its own view. Mixing views in one query is rejected.
required_advanced — advanced settings the view can’t run without (a Semrush region, a Mailchimp audience). Each entry names the advanced key and the message shown when it’s missing.
Field flags — single (must be the only dimension), deprecated (retired by the vendor; still resolves, may return nothing) and custom (a per-account definition, not part of the static catalog).

Other helpful endpoints:

GET /v1/clients/{id}/datasources — which sources a specific client has connected.
POST /v1/data/resource — selectable sub-resource values (campaigns, ad sets, videos) for filters.
POST /v1/datasources/accounts — the accounts, properties or pages a connection can be linked to.

Over MCP the same catalog is two tools — datasources → describe_datasource, which returns a datasource’s data views with their metrics, dimensions and required settings in one call. Agents call them in that order, no guessing. Live values are read by configuring a saved widget (add_data_widget) and refreshing it, not by querying ad hoc.

Common errors

Status	Cause	What to do
`422`	Missing/invalid field — no `metrics`, or an unknown `datasource_id`, `metric`, or `dimension` for that datasource. Identifiers are validated against the field catalog before the query runs, so a typo is rejected here rather than failing upstream.	Check the request against the table above and the field catalog; details are in `error.details`.
`404`	`client_id` doesn’t exist in your account.	Verify the ID via `GET /v1/clients`.
`502`	Upstream datasource error — not connected or an expired OAuth token.	Run `POST /v1/datasources/test` with the connection’s `auth_id` (from `GET /v1/datasources/auths`) to check it; if the token expired, reconnect the source in the app.

A 502 most often means the client’s OAuth token for that datasource has expired and needs reconnecting in the app — it’s not a bug in your request.

Overview

Concepts

Health

Users

Account

Company

Custom Domains

Branding

Clients

Folders

Projects

Project Changes

Pages

Search

Widgets

Data

Calculated Metrics

Goals

Custom Data

Billing

Datasources

Email

Media

Assets

PDF

Exports

Templates

Themes

Automations

Archive

Activity

Notifications

Request

Response

Finding valid identifiers

Common errors

​Request

​Response

​Finding valid identifiers

​Common errors

Request

Response

Finding valid identifiers

Common errors