API Documentation - Open Ad Metrics

Overview

The Open Ad Metrics API enables programmatic access to our powerful campaign analysis engine. Submit your advertising data with custom column mappings and receive detailed performance metrics, insights, and AI-powered recommendations as JSON.

API Version: 1.0

Last Updated: March 17, 2026

Protocol: HTTPS

Format: JSON

Getting Started

Follow these steps to start using the API:

1. Get Your Credentials

Obtain your Supabase project URL and anon key from your project settings.

2. Prepare Your Data

Format your campaign data as an array of objects with consistent column names.

3. Map Your Columns

Create a column mapping object that tells the API which fields contain which data.

4. Make Your Request

Send a POST request to the API endpoint with your data and mappings.

Authentication

The API uses Supabase authentication. Include your anon key in the request headers:

apikey: YOUR_SUPABASE_ANON_KEY
Content-Type: application/json

Security Note: Keep your API key secure. Never expose it in client-side code repositories or public websites.

API Endpoint

Base URL

https://[your-project-id].supabase.co

Endpoint

POST /functions/v1/analyze-data

Request Format

Request Body

Field	Type	Required	Description
`data`	Array	Yes	Array of campaign data objects
`columnMapping`	Object	Yes	Mapping of your columns to expected fields
`primaryKPI`	String	No	Primary KPI: "CPA", "ROAS", "POAS", or "Revenue"

Column Mapping Fields

Field	Required	Description
`primaryDimension`	Yes	Primary grouping (e.g., "Platform", "Campaign")
`secondaryDimension`	No	Secondary grouping
`tertiaryDimension`	No	Tertiary grouping
`spend`	Yes*	Column name for spend/cost
`conversions`	Yes*	Column name for conversions
`impressions`	No	Column name for impressions
`clicks`	No	Column name for clicks
`revenue`	No	Column name for revenue
`roas`	No	Column name for ROAS
`poas`	No	Column name for POAS

* Required for basic analysis

Response Format

Success Response (200 OK)

{
  "success": true,
  "data": {
    "totalSpend": 5000,
    "totalConversions": 250,
    "blendedCPA": 20,
    "overallCTR": 3.5,
    "totalRevenue": 15000,
    "overallROAS": 3.0,
    "platformData": [...],
    "topPerformer": {...},
    "worstPerformer": {...},
    "recommendations": [...]
  }
}

Response Fields

Field	Type	Description
`success`	Boolean	Whether the request succeeded
`data`	Object	Analysis results
`data.totalSpend`	Number	Total spend across all campaigns
`data.totalConversions`	Number	Total conversions
`data.blendedCPA`	Number	Blended cost per acquisition
`data.overallCTR`	Number	Overall click-through rate (%)
`data.platformData`	Array	Detailed metrics per dimension
`data.topPerformer`	Object	Best performing dimension
`data.recommendations`	Array	AI-generated recommendations

Examples

Basic Campaign Analysis

curl -X POST https://uzhsksrmqrmfwxnsvhbo.supabase.co/functions/v1/analyze-data \
  -H "Content-Type: application/json" \
  -H "apikey: YOUR_SUPABASE_ANON_KEY" \
  -d '{
    "data": [
      {
        "Platform": "Google Ads",
        "Spend": "2500",
        "Conversions": "120"
      }
    ],
    "columnMapping": {
      "primaryDimension": "Platform",
      "spend": "Spend",
      "conversions": "Conversions"
    },
    "primaryKPI": "CPA"
  }'

Multi-Dimensional Analysis

{
  "data": [
    {
      "Creative": "Video A",
      "Audience": "18-24",
      "Device": "Mobile",
      "Spend": "1000",
      "Conversions": "50",
      "Revenue": "3000"
    }
  ],
  "columnMapping": {
    "primaryDimension": "Creative",
    "secondaryDimension": "Audience",
    "tertiaryDimension": "Device",
    "spend": "Spend",
    "conversions": "Conversions",
    "revenue": "Revenue"
  },
  "primaryKPI": "ROAS"
}

Error Handling

Error Response Format

{
  "success": false,
  "error": "Error message describing what went wrong"
}

Common Errors

400 Bad Request

Invalid request format, missing required fields, or invalid data

401 Unauthorized

Missing or invalid API key

405 Method Not Allowed

Must use POST method

500 Internal Server Error

Server-side processing error

Rate Limits

The API follows standard Supabase Edge Function rate limits. For high-volume usage:

Implement request batching to combine multiple analyses
Cache results where possible to minimize repeated requests
Use appropriate retry logic with exponential backoff
Monitor response times and adjust request frequency

If you exceed rate limits, you'll receive a 429 Too Many Requests response. Implement retry logic with exponential backoff.

Data & Privacy

GDPR Compliance

Our API is fully GDPR compliant. We process your data only to provide the analysis service and do not store it permanently unless you explicitly create shareable reports.

Data Processing

Real-time Processing: Analysis data is processed in real-time and not stored
No Permanent Storage: Unless you create a share link, your data is not saved
30-Day Retention: Shared reports are stored for 30 days, then auto-deleted
Encryption: All data transmission uses HTTPS encryption
Regional Compliance: We comply with GDPR, CCPA/CPRA, PIPEDA, and Privacy Act

Your Rights

You have the right to:

Access your data
Request data deletion
Data portability
Object to processing

Learn More: See our Privacy Policy and Terms of Service for complete details.

Code Samples

JavaScript/TypeScript

async function analyzeCampaign() {
  const response = await fetch(
    'https://uzhsksrmqrmfwxnsvhbo.supabase.co/functions/v1/analyze-data',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'apikey': 'YOUR_SUPABASE_ANON_KEY'
      },
      body: JSON.stringify({
        data: [
          {
            Platform: 'Google Ads',
            Spend: '1000',
            Conversions: '50'
          }
        ],
        columnMapping: {
          primaryDimension: 'Platform',
          spend: 'Spend',
          conversions: 'Conversions'
        }
      })
    }
  );

  const result = await response.json();

  if (result.success) {
    console.log('Total Spend:', result.data.totalSpend);
    console.log('CPA:', result.data.blendedCPA);
  } else {
    console.error('Error:', result.error);
  }
}

Python

import requests
import json

def analyze_campaign():
    url = "https://uzhsksrmqrmfwxnsvhbo.supabase.co/functions/v1/analyze-data"
    headers = {
        "Content-Type": "application/json",
        "apikey": "YOUR_SUPABASE_ANON_KEY"
    }

    payload = {
        "data": [
            {
                "Platform": "Google Ads",
                "Spend": "1000",
                "Conversions": "50"
            }
        ],
        "columnMapping": {
            "primaryDimension": "Platform",
            "spend": "Spend",
            "conversions": "Conversions"
        }
    }

    response = requests.post(url, headers=headers, json=payload)
    result = response.json()

    if result.get("success"):
        print(f"Total Spend: {result['data']['totalSpend']}")
        print(f"CPA: {result['data']['blendedCPA']}")
    else:
        print(f"Error: {result.get('error')}")

analyze_campaign()

Node.js

const axios = require('axios');

async function analyzeCampaign() {
  try {
    const response = await axios.post(
      'https://uzhsksrmqrmfwxnsvhbo.supabase.co/functions/v1/analyze-data',
      {
        data: [
          {
            Platform: 'Google Ads',
            Spend: '1000',
            Conversions: '50'
          }
        ],
        columnMapping: {
          primaryDimension: 'Platform',
          spend: 'Spend',
          conversions: 'Conversions'
        }
      },
      {
        headers: {
          'Content-Type': 'application/json',
          'apikey': 'YOUR_SUPABASE_ANON_KEY'
        }
      }
    );

    if (response.data.success) {
      console.log('Results:', response.data.data);
    }
  } catch (error) {
    console.error('Error:', error.message);
  }
}

analyzeCampaign();

Support

Need help? We're here to assist:

API Support

Technical API questions

api@openadmetrics.com

Privacy Inquiries

Data protection questions

privacy@openadmetrics.com

General Support

General questions

support@openadmetrics.com

Documentation

More resources

Quick Start Guide