# Ad Metrics API
> Marketing and advertising metrics as an API — the everyday campaign maths, computed locally and deterministically and entirely currency-agnostic. The funnel endpoint takes any of impressions, clicks, conversions, spend and revenue and computes every metric the inputs allow: click-through rate (CTR), cost per click (CPC), cost per mille (CPM), conversion rate, cost per acquisition (CPA), average order value, return on ad spend (ROAS), return on investment (ROI) and profit — anything not derivable is returned as null rather than guessed. The roas endpoint focuses on profitability: ROAS, ROI and profit, and — given a gross margin — the break-even ROAS and gross profit, with a profitable flag. The target endpoint reverse-plans a campaign: from a conversion or revenue goal and your known rates it works out the required clicks, impressions and budget and the expected revenue and ROAS. Everything is computed locally and deterministically, so it is instant and private. Rates such as conversion_rate and ctr are given as fractions (0.05 = 5%). Ideal for marketing dashboards and reporting, media-buying and bid tools, agency and campaign planners, and e-commerce analytics. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 endpoints. This is advertising-metric maths; for loan and investment maths use a finance-calculator API.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/admetrics-api/..."
```

## Pricing
- **Free** (Free) — 9,735 calls/Mo, 2 req/s
- **Starter** ($11/Mo) — 19,350 calls/Mo, 8 req/s
- **Pro** ($31/Mo) — 243,500 calls/Mo, 20 req/s
- **Mega** ($69/Mo) — 1,260,000 calls/Mo, 50 req/s

## Endpoints

### Metrics

#### `GET /v1/funnel` — Funnel metrics (CTR/CPC/CPM/CVR/CPA/ROAS/ROI)

**Parameters:**
- `impressions` (query, optional, string) — Impressions Example: `100000`
- `clicks` (query, optional, string) — Clicks Example: `2000`
- `conversions` (query, optional, string) — Conversions Example: `100`
- `spend` (query, optional, string) — Spend Example: `1000`
- `revenue` (query, optional, string) — Revenue Example: `5000`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/admetrics-api/v1/funnel?impressions=100000&clicks=2000&conversions=100&spend=1000&revenue=5000"
```

**Response:**
```json
{
    "data": {
        "cpc": 0.5,
        "cpm": 10,
        "note": "Metrics are computed only where the required inputs are present; others are null. CTR/conversion rate/ROI are percentages.",
        "roas": 5,
        "input": {
            "spend": 1000,
            "clicks": 2000,
            "revenue": 5000,
            "conversions": 100,
            "impressions": 100000
        },
        "profit": 4000,
        "ctr_percent": 2,
        "roi_percent": 400,
        "cost_per_conversion": 10,
        "revenue_per_conversion": 50,
        "conversion_rate_percent": 5
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:57.779Z",
        "request_id": "312fdd69-0662-4a59-b60d-8716052c33af"
    },
    "status": "ok",
    "message": "Funnel metrics",
    "success": true
}
```

#### `GET /v1/roas` — ROAS, ROI, profit & break-even

**Parameters:**
- `spend` (query, required, string) — Ad spend Example: `1000`
- `revenue` (query, required, string) — Revenue Example: `5000`
- `margin` (query, optional, string) — Gross margin fraction (0-1) Example: `0.5`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/admetrics-api/v1/roas?spend=1000&revenue=5000&margin=0.5"
```

**Response:**
```json
{
    "data": {
        "note": "ROAS = revenue ÷ spend. Break-even ROAS = 1 ÷ gross margin. Gross profit = revenue × margin − spend.",
        "roas": 5,
        "input": {
            "spend": 1000,
            "margin": 0.5,
            "revenue": 5000
        },
        "profit": 4000,
        "profitable": true,
        "roi_percent": 400,
        "gross_profit": 1500,
        "break_even_roas": 2
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:57.883Z",
        "request_id": "978ac6e5-149c-40f9-b7bc-194b197a759c"
    },
    "status": "ok",
    "message": "ROAS & profitability",
    "success": true
}
```

#### `GET /v1/target` — Reverse-plan a campaign

**Parameters:**
- `target_conversions` (query, optional, string) — Goal: conversions Example: `200`
- `target_revenue` (query, optional, string) — Or goal: revenue
- `conversion_rate` (query, required, string) — Fraction e.g. 0.05 Example: `0.05`
- `ctr` (query, optional, string) — Fraction e.g. 0.02 Example: `0.02`
- `cpc` (query, optional, string) — Cost per click Example: `0.5`
- `aov` (query, optional, string) — Avg order value Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/admetrics-api/v1/target?target_conversions=200&conversion_rate=0.05&ctr=0.02&cpc=0.5&aov=50"
```

**Response:**
```json
{
    "data": {
        "note": "Reverse-plans the funnel: conversions ÷ conversion rate = clicks; ÷ CTR = impressions; × CPC = budget.",
        "input": {
            "aov": 50,
            "cpc": 0.5,
            "ctr": 0.02,
            "conversion_rate": 0.05,
            "target_conversions": 200
        },
        "expected_roas": 5,
        "required_budget": 2000,
        "required_clicks": 4000,
        "expected_revenue": 10000,
        "required_impressions": 200000
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.009Z",
        "request_id": "d6b390ce-e2ff-40b0-b55a-a4800b70dc1c"
    },
    "status": "ok",
    "message": "Campaign planning",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/admetrics-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "note": "Currency-agnostic. Rates such as conversion_rate and ctr are fractions (0.05 = 5%).",
        "service": "admetrics",
        "endpoints": {
            "/v1/roas": "ROAS, ROI, profit and (with a margin) break-even ROAS and gross profit.",
            "/v1/funnel": "Compute CTR, CPC, CPM, conversion rate, CPA, ROAS and ROI from impressions/clicks/conversions/spend/revenue.",
            "/v1/target": "Reverse-plan required clicks, impressions and budget from a conversion or revenue goal."
        },
        "description": "Marketing/advertising metrics: funnel rates (CTR/CPC/CPM/CVR/CPA/ROAS/ROI), profitability and campaign planning."
    },
    "meta": {
        "timestamp": "2026-06-03T17:41:58.121Z",
        "request_id": "2ad3b41f-8854-4d45-8ee0-17683335ef1e"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/admetrics-api
OpenAPI spec: https://www.oanor.com/api/admetrics-api/openapi.json