Quickstart: your first report via the API

This quickstart chains the core REST endpoints to take you from zero to a client report with live data. Every field is snake_case, and every call uses your API key as a Bearer token.

One step — connecting a data source — happens once in the Oviond app, because it needs an interactive OAuth consent. Everything else is pure API.

Before you start

An Oviond API key (Settings → API Keys), on a plan that includes API access.
Base URL: https://api.oviond.com. Set a couple of shell variables to follow along:

export OVIOND_API_KEY="oviond_..."
export OVIOND_BASE="https://api.oviond.com"

1. Verify your key

curl "$OVIOND_BASE/v1/users/me" -H "Authorization: Bearer $OVIOND_API_KEY"

A 200 with your profile confirms the key works. A 401 means the header is missing or the key is invalid; see Errors.

2. Create a client

Every project belongs to a client.

curl -X POST "$OVIOND_BASE/v1/clients" \
  -H "Authorization: Bearer $OVIOND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Demo",
    "website": "acme.com",
    "timezone": "UTC",
    "currency": "USD"
  }'

The response’s data.id (for example cliAbc123) is your client_id for the next steps.

3. Connect a data source (in the app)

Data-source connections require interactive OAuth, so connect them once in the app — open a project for the client and use the Data sources tab (see Connecting Data Sources). Once connected, confirm it over the API:

curl "$OVIOND_BASE/v1/clients/cliAbc123/datasources" \
  -H "Authorization: Bearer $OVIOND_API_KEY"

Note the datasource_id (e.g. ga4, gadw, fb-ads) — you’ll need it to query.

4. Create a report

curl -X POST "$OVIOND_BASE/v1/projects" \
  -H "Authorization: Bearer $OVIOND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Q1 Report",
    "type": "REPORT",
    "template": "BLANK",
    "client_id": "cliAbc123"
  }'

Use "type": "DASHBOARD" for a live dashboard instead of a point-in-time report. The response returns the new project’s id and nano_id. See the Create Project reference for the full set of layout and branding fields.

5. Pull live data

Now query real metric values from the connected source:

curl -X POST "$OVIOND_BASE/v1/data/query" \
  -H "Authorization: Bearer $OVIOND_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"
  }'

See Querying data for the full field reference, how to discover valid metrics and dimensions, and error handling.

Share a link: open the project in the app and use the Share dialog to publish a link (backed by the project’s nano_id).
Schedule delivery: create an automation to email the report on a recurring schedule.

Next steps

Querying data

Metrics, dimensions, date ranges, and comparisons.

Errors & request IDs

The response envelope and status codes.

Rate limits & retries

Stay within budget and retry safely.

Full API reference

Every endpoint, request, and response.

Overview

Sandbox

​Before you start

​1. Verify your key

​2. Create a client

​3. Connect a data source (in the app)

​4. Create a report

​5. Pull live data

​6. Share or schedule

​Next steps

Querying data

Errors & request IDs

Rate limits & retries

Full API reference

Before you start

1. Verify your key

2. Create a client

3. Connect a data source (in the app)

4. Create a report

5. Pull live data

6. Share or schedule

Next steps