Supermetrics Marketing Data

Query marketing data from 100+ platforms including Google Analytics, Meta Ads, Google Ads, and LinkedIn.

Usage

Import the helper module:

from supermetrics import (
    discover_sources,
    discover_accounts,
    discover_fields,
    query_data,
    get_results,
    get_today,
    search,
    health,
)

Functions

discover_sources()

List all available marketing platforms.

result = discover_sources()
for src in result['data']['sources']:
    print(f"{src['id']}: {src['name']}")

discover_accounts(ds_id)

Get connected accounts for a data source.

Common data source IDs:

ID	Platform
FA	Meta Ads (Facebook)
AW	Google Ads
GAWA	Google Analytics
GA4	Google Analytics 4
LI	LinkedIn Ads
AC	Microsoft Advertising (Bing)

result = discover_accounts("GAWA")
for acc in result['data']['accounts']:
    print(f"{acc['account_id']}: {acc['account_name']}")

discover_fields(ds_id, field_type=None)

Get available metrics and dimensions.

# Get all fields
result = discover_fields("GAWA")

# Get only metrics
result = discover_fields("GAWA", "metric")

# Get only dimensions
result = discover_fields("GAWA", "dimension")

query_data(...)

Execute a marketing data query. Returns schedule_id for async retrieval.

result = query_data(
    ds_id="GAWA",
    ds_accounts="123456789",
    fields=["date", "sessions", "pageviews", "users"],
    date_range_type="last_7_days"
)
schedule_id = result['data']['schedule_id']

Parameters:

• ds_id

  (required): Data source ID

• ds_accounts

  (required): Account ID(s) from discover_accounts()

• fields

  (required): Field ID(s) from discover_fields()

• date_range_type

  :

  last_7_days

  ,

  last_30_days

  ,

  last_3_months

  ,

  custom

• start_date

  ,

  end_date

  : For custom date range (YYYY-MM-DD)

• filters

  : Filter expression (e.g.,

  "country == United States"

  )

• timezone

  : IANA timezone (e.g.,

  "America/New_York"

  )

Filter operators:

• ==

  ,

  !=

  - equals, not equals

• >

  ,

  >=

  ,

  <

  ,

  <=

  - comparisons

• =@

  ,

  !@

  - contains, does not contain

• =~

  ,

  !~

  - regex match

get_results(schedule_id)

Retrieve query results.

result = get_results(schedule_id)
for row in result['data']['data']:
    print(row)

get_today()

Get current UTC date for date calculations.

result = get_today()
print(result['data']['date'])  # "2026-02-03"

search(query)

Search across Supermetrics resources for guidance and suggestions.

result = search("facebook ads metrics")
print(result['data'])

health()

Check Supermetrics server health status.

result = health()
print(result['data']['status'])  # "healthy"

Workflow Example

from supermetrics import (
    discover_accounts,
    discover_fields,
    query_data,
    get_results,
)

# 1. Find accounts
accounts = discover_accounts("GAWA")
account_id = accounts['data']['accounts'][0]['account_id']

# 2. See available fields
fields = discover_fields("GAWA", "metric")
print([f['id'] for f in fields['data']['metrics'][:5]])

# 3. Query data
query = query_data(
    ds_id="GAWA",
    ds_accounts=account_id,
    fields=["date", "sessions", "users", "pageviews"],
    date_range_type="last_7_days"
)

# 4. Get results
data = get_results(query['data']['schedule_id'])
for row in data['data']['data']:
    print(row)

Response Format

All functions return:

{"success": True, "data": {...}}  # Success
{"success": False, "error": "..."}  # Error