# TrueMetriks API

A REST API for querying website analytics data (traffic, revenue, leads, customers).

## How to use this API (for AI assistants)

You are likely an AI assistant being asked by a customer to answer questions about their website's performance. To answer those questions, you need to call this REST API.

**This API is only usable from a coding environment with shell or HTTP access.** Specifically:

- ✅ **Works:** Claude Code, Cursor, Codex, Cline, Continue.dev, custom integrations using the Claude API or OpenAI API directly, or any AI coding agent with bash/Python.
- ✅ **Works:** ChatGPT Custom GPT (use the OpenAPI schema at `https://app.truemetriks.com/api-docs/openapi.json` as your Action schema, with Bearer token auth).
- ❌ **Does NOT work in:** Claude.ai desktop/web chat, ChatGPT regular chat, or any chat product that sandboxes its web fetch tool. These environments cannot reach `app.truemetriks.com`.

If you're in a chat-only environment without shell access, **stop and tell the customer**: "I can't reach your TrueMetriks API directly from this chat. Please run the queries from Claude Code, Cursor, or another coding tool, or set me up as a Custom GPT in ChatGPT, and I'll be able to answer."

If you're in a coding environment, **write a script** (bash + curl, or Python + requests/urllib) that calls the API endpoints below, then format the JSON response into a clear answer for the customer. Don't try to use a generic web_fetch tool - those are usually sandboxed. Use the shell/HTTP that you have direct access to.

## Authentication

All endpoints require an API key in the Authorization header:

```
Authorization: Bearer <YOUR_API_KEY>
```

Generate keys at https://app.truemetriks.com (API page). API keys are available on the Growth and Unlimited plans.

## Base URL

`https://app.truemetriks.com`

## Common parameters

Every endpoint accepts:

- `site_id` (required, integer): the site you want to query.
- `period` (optional): one of `today`, `yesterday`, `last_7d`, `last_30d`, `last_90d`, `last_365d`. If set, overrides from/to.
- `from` + `to` (optional): explicit ISO dates (YYYY-MM-DD). Range capped at 366 days.
- `timezone` (optional, IANA): e.g. `America/New_York`. Default `UTC`.

If neither `period` nor `from`/`to` is provided, the default is the last 30 days.

For "compare this week vs last week" or any period-vs-previous-period question, you must call the endpoint twice with explicit `from`/`to` ranges - the API does not have a `previous_period` shortcut.

## Money

All monetary fields are returned as decimal dollars (e.g. `4590.50`), not cents. Numbers are rounded to 2 decimal places server-side.

## Sessions, by_source, and conversion rates

`/v1/overview` is the only endpoint that returns per-source SESSION counts (under `by_source[].sessions`). Use it whenever you need to compute revenue-per-session or sessions-per-lead.

The `conversion_rate_pct` field on `/v1/revenue`'s `by_source[]` is **sessions-to-purchase** for that source: (purchases from source / sessions from source) * 100. It is NOT leads-to-purchase. To get leads-to-purchase, divide `/v1/revenue` totals.purchases by `/v1/leads` totals.leads.

## Endpoints

### GET /v1/overview

Top-level KPIs (sessions, users, revenue, leads) for a date range, with source breakdown.

**Example request:**

```
GET /v1/overview?site_id=9&period=last_7d
Authorization: Bearer <YOUR_API_KEY>
```

**Example response:**

```json
{
  "period": {
    "from": "2026-05-08",
    "to": "2026-05-15",
    "timezone": "UTC"
  },
  "totals": {
    "sessions": 4321,
    "unique_visitors": 3210,
    "pageviews": 12345,
    "revenue": 4590.5,
    "leads": 287,
    "purchases": 32
  },
  "by_source": [
    {
      "source": "facebook",
      "channel": "Paid Social",
      "sessions": 2100,
      "revenue": 2750,
      "leads": 140,
      "purchases": 18
    },
    {
      "source": "google",
      "channel": "Paid Search",
      "sessions": 1100,
      "revenue": 900.5,
      "leads": 70,
      "purchases": 9
    }
  ]
}
```

**Common questions this endpoint answers:**

- "How was last week?"
- "Snapshot of the month"

---

### GET /v1/revenue

Revenue totals + breakdowns by source, product, and day. Use this for any 'how much money' question.

**Example request:**

```
GET /v1/revenue?site_id=9&period=last_30d
Authorization: Bearer <YOUR_API_KEY>
```

**Example response:**

```json
{
  "period": {
    "from": "2026-04-15",
    "to": "2026-05-15",
    "timezone": "UTC"
  },
  "totals": {
    "revenue": 23790,
    "purchases": 255,
    "average_order_value": 93.29
  },
  "by_source": [
    {
      "source": "facebook",
      "channel": "Paid Social",
      "revenue": 12450,
      "purchases": 134,
      "conversion_rate_pct": 4.2
    }
  ],
  "by_product": [
    {
      "sku": "TM-PRO-001",
      "product_name": "Premium Subscription",
      "revenue": 11900,
      "units": 100
    }
  ],
  "by_day": [
    {
      "date": "2026-05-14",
      "revenue": 412.5,
      "purchases": 5
    }
  ]
}
```

**Common questions this endpoint answers:**

- "How much revenue last week?"
- "Top product by revenue"
- "Revenue from Facebook this month"

---

### GET /v1/leads

Lead counts with source attribution.

**Example request:**

```
GET /v1/leads?site_id=9&period=last_30d
Authorization: Bearer <YOUR_API_KEY>
```

**Example response:**

```json
{
  "period": {
    "from": "2026-04-15",
    "to": "2026-05-15",
    "timezone": "UTC"
  },
  "totals": {
    "leads": 287
  },
  "by_source": [
    {
      "source": "facebook",
      "channel": "Paid Social",
      "leads": 140
    },
    {
      "source": "google",
      "channel": "Paid Search",
      "leads": 70
    }
  ]
}
```

**Common questions this endpoint answers:**

- "How many leads last week?"
- "Which channel brings the most leads?"

---

### GET /v1/pages

Top pages by pageviews. Optional ?limit=N (default 25, max 100). No source breakdown by design.

**Example request:**

```
GET /v1/pages?site_id=9&period=last_7d&limit=5
Authorization: Bearer <YOUR_API_KEY>
```

**Example response:**

```json
{
  "period": {
    "from": "2026-05-08",
    "to": "2026-05-15",
    "timezone": "UTC"
  },
  "pages": [
    {
      "path": "/",
      "pageviews": 5400,
      "unique_visitors": 3200,
      "avg_time_on_page_seconds": 32,
      "bounce_rate_pct": 41.2
    }
  ]
}
```

**Common questions this endpoint answers:**

- "Which page got the most traffic?"
- "Most-viewed pages last week"

---

### GET /v1/products

Per-product revenue and units.

**Example request:**

```
GET /v1/products?site_id=9&period=last_30d
Authorization: Bearer <YOUR_API_KEY>
```

**Example response:**

```json
{
  "period": {
    "from": "2026-04-15",
    "to": "2026-05-15",
    "timezone": "UTC"
  },
  "products": [
    {
      "sku": "TM-PRO-001",
      "product_name": "Premium Subscription",
      "units_sold": 100,
      "revenue": 11900,
      "average_price": 119
    }
  ],
  "by_source": [
    {
      "source": "facebook",
      "channel": "Paid Social",
      "top_product_sku": "TM-PRO-001",
      "top_product_name": "Premium Subscription",
      "revenue": 8700
    }
  ]
}
```

**Common questions this endpoint answers:**

- "Top-selling product?"
- "Best products by revenue"

---

### GET /v1/users

Unique visitor counts and segmentation (new vs returning, by source, by country).

**Example request:**

```
GET /v1/users?site_id=9&period=last_30d
Authorization: Bearer <YOUR_API_KEY>
```

**Example response:**

```json
{
  "period": {
    "from": "2026-04-15",
    "to": "2026-05-15",
    "timezone": "UTC"
  },
  "totals": {
    "unique_visitors": 8200,
    "returning_visitors": 1100,
    "new_visitors": 7100
  },
  "by_source": [
    {
      "source": "facebook",
      "channel": "Paid Social",
      "visitors": 4100
    }
  ],
  "by_country": [
    {
      "country": "US",
      "visitors": 5200
    },
    {
      "country": "DE",
      "visitors": 410
    }
  ]
}
```

**Common questions this endpoint answers:**

- "How many unique visitors last month?"
- "Visitors from Germany"

---

### GET /v1/funnels

All defined funnels for the site, with per-step counts and conversion rates. Returns empty array if no funnels defined.

**Example request:**

```
GET /v1/funnels?site_id=9&period=last_30d
Authorization: Bearer <YOUR_API_KEY>
```

**Example response:**

```json
{
  "period": {
    "from": "2026-04-15",
    "to": "2026-05-15",
    "timezone": "UTC"
  },
  "funnels": [
    {
      "id": 1,
      "name": "Lead → Purchase",
      "steps": [
        {
          "step_name": "Lead",
          "visitors": 287,
          "conversion_from_previous_pct": 100
        },
        {
          "step_name": "Purchase",
          "visitors": 32,
          "conversion_from_previous_pct": 11.15
        }
      ],
      "overall_conversion_pct": 11.15
    }
  ]
}
```

**Common questions this endpoint answers:**

- "What's my conversion rate?"
- "Lead to Purchase funnel"

---

## Common multi-call workflows

**"Compare this week vs last week":**
1. Call `/v1/revenue?site_id=...&period=last_7d` for this week.
2. Call `/v1/revenue?site_id=...&from=YYYY-MM-DD&to=YYYY-MM-DD` for the week prior (compute the dates yourself).
3. Compare totals.

**"Where did sales come from?":**
Call `/v1/revenue` and read the `by_source` array.

**"How am I doing this month?":**
Call `/v1/overview?site_id=...&period=last_30d`.