Querying Data

The query endpoint is the core of the Oviond API. It fetches and formats data from any integration using a consistent request/response structure.

Endpoint

POST /v1/integrations/{id}/query

Request Body

Date Ranges

Every query requires both a current and previous date range for comparison:

{
  "dateRange": {
    "current": {
      "startDate": "2025-01-01",
      "endDate": "2025-01-31"
    },
    "previous": {
      "startDate": "2024-12-01",
      "endDate": "2024-12-31"
    }
  }
}

Dates use YYYY-MM-DD format.

Metrics

Metrics are the numeric values you want to fetch. Each integration defines its own metric IDs — browse them in the Field Reference.

{
  "metrics": ["sessions", "pageviews", "bounce_rate"]
}

Dimensions

Dimensions break down metrics by a category (e.g. by country, by page, by campaign). Most integrations accept a single dimension:

{
  "dimension": "country"
}

Some integrations support multiple dimensions via the dimensions array.

Response Format

All query responses use the FormattedResult structure:

{
  "success": true,
  "data": {
    "current": [
      { "date": "2025-01-01", "sessions": 150, "pageviews": 420 }
    ],
    "currentSummary": {
      "sessions": 4500,
      "pageviews": 12600
    },
    "previous": [
      { "date": "2024-12-01", "sessions": 130, "pageviews": 380 }
    ],
    "previousSummary": {
      "sessions": 4100,
      "pageviews": 11200
    },
    "state": "ACTIVE"
  }
}

The state field indicates:

• ACTIVE — data was returned successfully
• NO_DATA — query succeeded but no data in range
• ERROR — something went wrong

Data Views

Integrations can have multiple data views representing different data sets. For example, a social media integration might have "posts", "audience", and "stories" data views.

Check available data views for an integration:

curl https://api.oviond.com/v1/integrations/{id}