Introduction

Convrs is a lightweight website analytics platform built for modern SaaS products.

Add a single script to your website and start tracking visitors, pageviews, conversions, custom events, and revenue attribution in real time.

See the Quickstart guide to get set up in under two minutes.

Quick Start

Get started with Convrs in under two minutes.

1. Create a Website

Create a website in your Convrs dashboard and copy your Website ID.

2. Add the Script

Paste the script into your website's <head> or before the closing </body> tag.

<script
  async
  src="https://convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

3. Open Your Dashboard

Visit your Convrs dashboard and start exploring your analytics.

Data typically appears within a few seconds of the first pageview.

Replace YOUR_WEBSITE_ID with the Website ID from your Convrs dashboard.

HTML & Vanilla JS

The simplest installation — add the Convrs tracking script anywhere in your HTML.

<!DOCTYPE html>
<html>
  <head>
    <title>My Site</title>

    <!-- Convrs Analytics -->
    <script
      async
      src="https://convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID">
    </script>
  </head>

  <body>
    <!-- Your content -->
  </body>
</html>

Using async ensures the script never blocks page rendering.

Next.js

Use the built-in Next.js Script component so Convrs loads with the correct strategy.

App Router (Next.js 13+)

Add this to your app/layout.tsx:

import Script from 'next/script';

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        {children}

        <Script
          src="https://convrs.dev/script.js"
          data-website-id="YOUR_WEBSITE_ID"
          strategy="afterInteractive"
        />
      </body>
    </html>
  );
}

Pages Router

Add this to pages/_app.tsx:

import Script from 'next/script';
import type { AppProps } from 'next/app';

export default function App({
  Component,
  pageProps,
}: AppProps) {
  return (
    <>
      <Component {...pageProps} />

      <Script
        src="https://convrs.dev/script.js"
        data-website-id="YOUR_WEBSITE_ID"
        strategy="afterInteractive"
      />
    </>
  );
}

Convrs automatically tracks client-side route changes in Next.js.

React (Vite / CRA)

Install Convrs in your React application to start tracking pageviews, visitors, and custom events automatically.

Option A — index.html (Recommended)

The simplest approach is to add the Convrs script directly to your index.html file.

Vite

<!-- index.html -->

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <title>My App</title>
  </head>

  <body>
    <div id="root"></div>

    <script
      async
      src="https://convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID">
    </script>

    <script type="module" src="/src/main.tsx"></script>
  </body>
</html>

Create React App

<!-- public/index.html -->

<body>
  <div id="root"></div>

  <script
    async
    src="https://convrs.dev/script.js"
    data-website-id="YOUR_WEBSITE_ID">
  </script>
</body>

Option B — Load via useEffect

If you prefer to load Convrs dynamically, add the script once when your application mounts.

import { useEffect } from 'react';

export default function App() {
  useEffect(() => {
    const script = document.createElement('script');

    script.src = 'https://convrs.dev/script.js';
    script.async = true;

    script.setAttribute(
      'data-website-id',
      'YOUR_WEBSITE_ID'
    );

    document.head.appendChild(script);

    return () => {
      document.head.removeChild(script);
    };
  }, []);

  return <div>Your App</div>;
}

Vue.js

index.html (Recommended)

<body>
  <div id="app"></div>

  <script
    async
    src="https://convrs.dev/script.js"
    data-website-id="YOUR_WEBSITE_ID">
  </script>

  <script type="module" src="/src/main.ts"></script>
</body>

App.vue

<script setup>
import { onMounted } from 'vue';

onMounted(() => {
  const script = document.createElement('script');

  script.src = 'https://convrs.dev/script.js';
  script.async = true;

  script.setAttribute(
    'data-website-id',
    'YOUR_WEBSITE_ID'
  );

  document.head.appendChild(script);
});
</script>

<template>
  <RouterView />
</template>

Convrs automatically tracks Vue Router navigation.

Nuxt.js

Use Nuxt's built-in head management to load Convrs on every page.

nuxt.config.ts (Recommended)

export default defineNuxtConfig({
  app: {
    head: {
      script: [
        {
          src: 'https://convrs.dev/script.js',
          'data-website-id': 'YOUR_WEBSITE_ID',
          async: true,
        },
      ],
    },
  },
});

app.vue

<script setup>
useHead({
  script: [
    {
      src: 'https://convrs.dev/script.js',
      'data-website-id': 'YOUR_WEBSITE_ID',
      async: true,
    },
  ],
});
</script>

<template>
  <NuxtPage />
</template>

Convrs automatically tracks Nuxt route changes.

SvelteKit

Add the Convrs script to your root layout.

<!-- src/routes/+layout.svelte -->

<svelte:head>
  <script
    async
    src="https://convrs.dev/script.js"
    data-website-id="YOUR_WEBSITE_ID">
  </script>
</svelte:head>

<slot />

Convrs automatically tracks client-side navigation and page changes.

Remix

Add Convrs to your root application layout.

import {
  Links,
  Meta,
  Outlet,
  Scripts,
  ScrollRestoration,
} from "@remix-run/react";

export default function App() {
  return (
    <html lang="en">
      <head>
        <Meta />
        <Links />

        <script
          async
          src="https://convrs.dev/script.js"
          data-website-id="YOUR_WEBSITE_ID"
        />
      </head>

      <body>
        <Outlet />
        <ScrollRestoration />
        <Scripts />
      </body>
    </html>
  );
}

Convrs automatically tracks route transitions in Remix applications.

Astro

Add Convrs to your base layout.

---
---
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />

    <script
      async
      src="https://convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID">
    </script>

    <slot name="head" />
  </head>

  <body>
    <slot />
  </body>
</html>

If you're using Astro View Transitions, add transition:persist to the script tag to prevent reinitialization.

Gatsby

Install Convrs globally using Gatsby SSR APIs.

gatsby-ssr.js

import React from "react";

export const onRenderBody = ({
  setHeadComponents,
}) => {
  setHeadComponents([
    <script
      key="convrs"
      async
      src="https://convrs.dev/script.js"
      data-website-id="YOUR_WEBSITE_ID"
    />,
  ]);
};

gatsby-browser.js

// Convrs automatically tracks route changes.
// No additional setup is required.

Gatsby uses the History API, which Convrs tracks automatically.

WordPress

There are two ways to install Convrs on WordPress.

Option A — functions.php

function convrs_analytics_script() {
    echo '<script async src="https://convrs.dev/script.js" data-website-id="YOUR_WEBSITE_ID"></script>';
}

add_action('wp_head', 'convrs_analytics_script');

Option B — Plugin

Install a plugin such as:

• Insert Headers and Footers
• WPCode

Then paste:

<script
  async
  src="https://convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

into the Header section.

If you're using caching plugins such as WP Rocket or W3 Total Cache, ensure the script remains present in cached pages.

Webflow

Webflow allows custom code to be added globally across your site.

Installation

1. Open your Webflow project.
2. Click Project Settings.
3. Open the Custom Code tab.
4. Paste the following into Head Code:

<script
  async
  src="https://convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

1. Save changes.
2. Republish your website.

Convrs will immediately begin tracking pageviews once your site is published.

Shopify

Install Convrs across your entire Shopify storefront.

Installation

1. Open your Shopify Admin.
2. Navigate to Online Store → Themes.
3. Select Actions → Edit Code.
4. Open layout/theme.liquid.
5. Paste the following before the closing </head> tag:

<script
  async
  src="https://convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID">
</script>

1. Save the file.

Convrs automatically tracks storefront pages including product pages, collection pages, cart pages, and landing pages.

Convrs does not track activity inside the Shopify Admin dashboard.

NPM SDK

Install Convrs as an npm package for type-safe analytics tracking in JavaScript and TypeScript applications.

Perfect for React, Next.js, Vue, Nuxt, SvelteKit, Remix, Astro, and other modern web frameworks.

Why use the SDK?

• TypeScript support
• Framework agnostic
• Automatic pageview tracking
• User identification
• Offline-ready

Installation

npm install @convrs/sdk

Quick Start

import { initConvrs } from "@convrs/sdk";

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
});

Track Events

convrs.track("signup", {
  source: "homepage",
});

Identify Users

convrs.identify("user_123", {
  email: "user@example.com",
  plan: "pro",
});

React / Next.js Example

lib/analytics.ts

import { initConvrs } from "@convrs/sdk";

let convrs: any = null;

export async function getAnalytics() {
  if (!convrs) {
    convrs = await initConvrs({
      websiteId:
        process.env.NEXT_PUBLIC_CONVRS_WEBSITE_ID!,
      autoCapturePageviews: true,
    });
  }

  return convrs;
}

Automatic Pageview Tracking

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
  autoCapturePageviews: true,
});

Configuration Options

Example Configuration

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
  debug: true,
  allowLocalhost: true,

  autoCapturePageviews: {
    trackHashChanges: true,
  },
});

See the API Reference for track(), identify(), trackPageview(), flush(), reset(), and cross-domain tracking.

Script Options

The Convrs tracking script accepts several optional data-* attributes to customize its behavior.

Example

<script
  async
  src="https://convrs.dev/script.js"
  data-website-id="YOUR_WEBSITE_ID"
  data-api="https://analytics.yourdomain.com/api/track"
  data-debug="true"
  data-allow-localhost="true"
  data-allow-file-protocol="true">
</script>

Only data-website-id is required. All other attributes are optional and should only be used when needed.

API Reference

The Convrs SDK exposes a simple API for tracking events, pageviews, and user identification.

track()

Track a custom event.

Syntax

convrs.track(eventName, properties?)

Parameters

Examples

convrs.track("signup");

convrs.track("purchase", {
  amount: 99,
  currency: "USD",
  plan: "Pro",
});

identify()

Associate events with a user.

Syntax

convrs.identify(userId, traits?)

Parameters

Examples

convrs.identify("user_123");

convrs.identify("user_123", {
  email: "user@example.com",
  name: "John Doe",
  plan: "Pro",
});

trackPageview()

Manually track a pageview.

Most applications do not need this because pageviews are tracked automatically when autoCapturePageviews is enabled.

Track Current Page

convrs.trackPageview();

Track Custom Path

convrs.trackPageview("/pricing");

flush()

Immediately send all queued events.

Syntax

await convrs.flush();

Example

await convrs.flush();

Useful before:

• Page unloads
• Checkout redirects
• Critical conversion events

reset()

Reset the current visitor and session.

Syntax

convrs.reset();

Example

function logout() {
  convrs.reset();
}

Useful when a user logs out.

getConvrsClient()

Access the initialized Convrs client anywhere in your application.

Syntax

import { getConvrsClient } from "@convrs/sdk";

const convrs = getConvrsClient();

Example

import { getConvrsClient } from "@convrs/sdk";

const convrs = getConvrsClient();

convrs.track("feature_used");

buildCrossDomainUrl()

Generate a URL containing Convrs tracking parameters.

Syntax

convrs.buildCrossDomainUrl(url);

Example

const url = convrs.buildCrossDomainUrl(
  "https://app.example.com/signup"
);

Result:

https://app.example.com/signup?_cv_vid=xxx&_cv_sid=xxx

getTrackingParams()

Retrieve the current visitor and session identifiers.

Syntax

const params = convrs.getTrackingParams();

Example

const params = convrs.getTrackingParams();

console.log(params);

Result:

{
  visitorId: "visitor_123",
  sessionId: "session_456"
}

Complete Example

import { initConvrs } from "@convrs/sdk";

const convrs = await initConvrs({
  websiteId: "YOUR_WEBSITE_ID",
});

convrs.identify("user_123", {
  plan: "Pro",
});

convrs.track("signup");

convrs.track("purchase", {
  amount: 99,
  currency: "USD",
});

await convrs.flush();

Tracking Events

Beyond automatic pageview tracking, Convrs lets you send custom events to measure important user actions throughout your application.

Custom events can be used to track:

• Signups
• Purchases
• Feature usage
• Form submissions
• Button clicks
• Checkout flow events
• Marketing conversions

All custom events appear in your Convrs dashboard and can be used for funnels, conversion tracking, and revenue attribution.

Syntax

window.convrs(eventName, properties)

Event names should be descriptive and consistent. Examples: signup, purchase, invite_sent, checkout_started.

Event Examples

Button Click

<button onclick="window.convrs('cta_clicked', { location: 'hero' })">
  Get Started
</button>

Form Submission

document
  .querySelector('#signup-form')
  .addEventListener('submit', () => {
    window.convrs('signup_submitted');
  });

React — Button Click

function UpgradeButton() {
  function handleClick() {
    window.convrs('upgrade_clicked', {
      plan: 'pro',
      source: 'pricing_page',
    });

    // Open checkout
  }

  return (
    <button onClick={handleClick}>
      Upgrade to Pro
    </button>
  );
}

E-commerce — Add to Cart

window.convrs('add_to_cart', {
  product_id: 'sku_1234',
  product_name: 'Wireless Headphones',
  price: 79.99,
  currency: 'USD',
});

Purchase Completed

window.convrs('purchase', {
  order_id: 'order_123',
  amount: 99,
  currency: 'USD',
  plan: 'pro',
});

Video Played

document
  .querySelector('#hero-video')
  .addEventListener('play', () => {
    window.convrs('video_played', {
      video: 'hero_demo',
    });
  });

Checkout Started

window.convrs('checkout_started', {
  plan: 'pro',
  billing_cycle: 'monthly',
});

Invite Sent

window.convrs('invite_sent', {
  team_size: 5,
});

Event Properties

Properties provide additional context for an event.

window.convrs('signup', {
  plan: 'pro',
  source: 'pricing_page',
  campaign: 'summer_launch',
});

These properties can be used to better understand user behavior and conversion patterns.

Best Practices

• Use lowercase event names.
• Use snake_case for event names.
• Keep event names consistent across your application.
• Attach meaningful properties to important events.
• Avoid sending sensitive user information.

Good examples:

window.convrs('signup');
window.convrs('checkout_started');
window.convrs('purchase');
window.convrs('invite_sent');

Avoid:

window.convrs('Clicked Button');
window.convrs('Event 1');
window.convrs('test');

Convrs automatically tracks pageviews and route changes. Custom events should be used for actions that represent meaningful user behavior.

Modern AI tools read your site before most humans do. ChatGPT fetches your pricing page to answer a question about it, Googlebot re-indexes your docs, GPTBot pulls your blog for training data — Bot traffic tracking shows you all of it, broken down by who's asking and why.

Bot traffic tracking is included in your Convrs plan. It isn't a separate add-on.

Get started

Install the server-side package, add one call to your backend, deploy. This runs separately from Convrs's normal browser tracking script — bots skip your frontend JavaScript, so this has to run server-side.

Install @convrs/ai-bot-sdk on npm

1. Install

npm install @convrs/ai-bot-sdk

2. Add it to your server

Most common setup — Next.js middleware:

// middleware.ts
import { createBotTrackingMiddleware } from "@convrs/ai-bot-sdk";

const trackBots = createBotTrackingMiddleware({
  siteId: "YOUR_SITE_ID",
});

export function middleware(
  request: Request,
  context: { waitUntil: (p: Promise<unknown>) => void }
) {
  trackBots(request, context);
}

export const config = {
  // Keep crawler-facing files reachable: robots.txt, llms.txt, sitemaps.
  matcher: ["/((?!api|_next/static|_next/image|favicon.ico).*)"],
};

3. Deploy and check your dashboard

After deploying, open your Convrs dashboard and look for the Bot traffic card. Filter by AI Answers, Indexing, or Training, and switch between the timeline and the per-provider breakdown.

If nothing shows up right away, that's expected — you're waiting for a real crawler to visit, not a human pageview. Try curl-ing your own site with a known bot's user-agent to confirm the pipeline end to end (see Testing your setup below).

What gets tracked

Every detected bot is classified into one of four categories:

Classification covers 20+ vendors out of the box — OpenAI, Anthropic, Google, Perplexity, Microsoft, Apple, Amazon, Meta, xAI, Mistral, Baidu, Alibaba, ByteDance, DeepSeek, Cohere, Common Crawl, and more. New vendors get added to the SDK's registry over time with no config change needed on your end.

Crawler-facing files

These are always tracked when a known bot requests them, even though they'd normally be filtered out as "not a real page":

• /robots.txt
• /llms.txt and /llms-full.txt
• /sitemap.xml and other sitemap files
• Any path ending in .xml under /sitemap/ or /sitemaps/

Everything else under your default-ignored prefixes (/api, /_next, /static, /assets, and similar) and default-ignored file extensions (.css, .js, .png, etc.) is skipped, since those are near-never what a person actually means by "did a bot visit my site."

How it works

On every request, the SDK checks the method, the User-Agent, and the path — in that order, bailing out as early as possible — before deciding whether to send anything:

1. Is this a GET/HEAD request? (configurable)
2. Does the User-Agent match a known bot? If not, stop here — nothing is sent.
3. Is the path a static asset, an ignored prefix, or over the length limit?
4. Send a small event in the background and return immediately.

The event itself only carries the raw User-Agent, IP, URL, and status code — vendor and category are always re-derived on the server, not trusted from the client. That keeps a caller from spoofing, say, a training crawler as an answer agent, and means crawler definitions can be updated on Convrs's side without every integration needing a package bump.

Platform examples

Next.js middleware

See Get started above.

Express

import express from "express";
import { createExpressBotMiddleware } from "@convrs/ai-bot-sdk";

const app = express();

app.use(createExpressBotMiddleware({ siteId: "YOUR_SITE_ID" }));

The Express adapter calls next() immediately, then attaches a finish listener and sends the event after your response has already gone out — your request handler never waits on it.

Generic Request/Response handler

If your framework gives you a request object up front and a response object later:

import { withBotTracking } from "@convrs/ai-bot-sdk";

export const GET = withBotTracking(
  async (request: Request) => {
    return new Response("ok");
  },
  { siteId: "YOUR_SITE_ID" }
);

If you only have the request and not the eventual response, request-only tracking still captures which page the bot hit — it just won't include a status code:

import { trackBotRequest } from "@convrs/ai-bot-sdk";

export function middleware(request: Request, context: { waitUntil: Function }) {
  trackBotRequest(request, context, { siteId: "YOUR_SITE_ID" });
}

Custom hosts behind an internal hostname

If your runtime hands the SDK an internal address (localhost, 0.0.0.0) instead of your public one, set it explicitly:

trackBotRequest(request, context, {
  siteId: "YOUR_SITE_ID",
  publicOrigin: "https://example.com",
});

Convrs still validates the resulting hostname against your site configuration and preserves the original path and query string.

Use without Node.js

Any backend that can send an HTTPS POST can report crawler traffic directly — no npm package required.

POST https://ingest.convrs.dev/api/ai-crawls
Content-Type: application/json
Authorization: Bearer cvbot_...    (only if you've enabled required auth)

Request body:

{
  "siteId": "YOUR_SITE_ID",
  "domain": "example.com",
  "url": "https://example.com/docs/get-started",
  "referrer": null,
  "bot": {
    "userAgent": "Mozilla/5.0 ... ChatGPT-User/1.0",
    "ip": "203.0.113.10",
    "statusCode": 200,
    "source": "server_middleware"
  }
}

A tracked-or-safely-ignored request returns 202 with a body indicating whether it was actually recognized as a bot:

{ "success": true, "tracked": true, "category": "training_crawler" }

or, for a user-agent that isn't a known bot:

{ "success": true, "tracked": false, "reason": "not_a_bot" }

Optional request authentication

Add a site-specific token without touching your existing integration:

1. Open your Bot traffic card settings and generate a token.
2. Add it to your SDK config or raw HTTP header.
3. Once deployed, flip on Reject unauthenticated requests.

createBotTrackingMiddleware({
  siteId: "YOUR_SITE_ID",
  authToken: process.env.CONVRS_BOT_TOKEN,
});

Keep the cvbot_... token server-side only — never in frontend code, a public repo, logs, or a URL. Enforcement is off until you explicitly enable it, so adding a token doesn't change existing behavior on its own. Rotating or deleting the token takes effect immediately.

Filtering categories

By default every category is tracked. Turn individual ones off if you only care about specific crawler types:

createBotTrackingMiddleware({
  siteId: "YOUR_SITE_ID",
  skipAnswerAgents: true,
  skipIndexCrawlers: true,
  skipTrainingCrawlers: true,
  skipOtherBots: true,
});

Most sites should leave the defaults on and filter later in the dashboard — turning a category off here means that traffic is never sent at all, not just hidden.

Privacy checklist

• Call the ingest endpoint (directly or via the SDK) only from your backend. Never from browser JavaScript, and never for regular human traffic.
• The SDK only ever sends the fields listed above — it doesn't forward cookies, auth headers, request bodies, or other visitor data.
• Prefer URLs without query parameters where you can. If query params carry anything sensitive, strip them before the URL reaches the SDK.
• Treat any IP you pass as untrusted unless it's coming through a proxy you control that strips client-supplied forwarding headers.

Testing your setup

curl -X POST https://ingest.convrs.dev/api/ai-crawls \
  -H "Content-Type: application/json" \
  -d '{"siteId":"YOUR_SITE_ID","url":"https://example.com/","bot":{"userAgent":"GPTBot/1.1","source":"manual-test"}}'

Expect 202 with tracked: true. Then check your dashboard's Bot traffic card for the new entry — it should land within a few seconds.

Where to find the data

Open your dashboard and look for the Bot traffic card. Switch between AI Answers, Indexing, and Training tabs, see the timeline for the selected category, and check the provider breakdown on the side for exact counts per vendor.

Track social mentions on your analytics chart

See when your brand is mentioned on X directly on your main analytics chart — no more guessing whether a traffic spike came from social media or somewhere else.

Requires a Convrs Growth plan.

Why track mentions?

Knowing when — and where — people are talking about your product helps you:

• Connect social buzz to revenue — see which mentions actually turned into traffic and sales, not just noise.
• Catch viral moments early — spot a spike in mentions while it's happening, not two days later when you check analytics.
• Time your launches — ship a campaign when conversation about your brand is already warm.

How it works

When someone mentions one of your tracked keywords on X, Convrs picks it up automatically and overlays it on your main analytics chart as social activity.

Hovering a day with activity shows:

• The author's avatar, stacked alongside anyone else who mentioned you that day
• A short preview of the post content, right in the chart tooltip
• How that day's mentions line up against your visitor and revenue numbers

If there's more activity than fits in the tooltip preview, a View all button opens the full list for that day — every mention, with the full post content, author, and a link out to the original post.

X mentions

Convrs searches X for your tracked keywords and your domain, and surfaces any tweet that mentions your brand.

Set up mention tracking

1. Go to Settings → Integrations.
2. Find the Twitter / X card.
3. Click the Mentions tab.
4. Add the keywords you want tracked.

Keyword rules

• 4–15 characters per keyword
• Matching is case-insensitive
• Include the @ symbol to track handle mentions (e.g. @convrsdev)
• Avoid generic single words — they'll mostly surface noise, not signal

Your workspace's domain is tracked automatically — you don't need to add it as a keyword yourself.

A note on connection status

The Twitter / X card shows whether your workspace currently has an active X connection. You can still add keywords and link-attribution accounts before connecting — they'll just sit ready and start surfacing mentions as soon as the connection is active.

Best practices

• Track your brand and product names — the highest-signal keywords you can add.
• Track campaign hashtags — add a hashtag right when a campaign launches so you catch the conversation from day one.
• Skip generic terms — words like "analytics" or "software" will flood your mention feed with unrelated noise.

Go further

Mentions tell you that people are talking about you. Pair this with X link attribution to see exactly which tweets are turning that conversation into visitors and revenue.

See which tweets drive your traffic and revenue

Referrer data full of generic t.co links doesn't tell you much. Convrs's X integration matches those links back to the actual tweets, so you can see exactly which posts are sending traffic — and revenue — to your site.

Requires a Convrs Growth plan.

Why this matters

A shortened link tells you nothing about what's actually working. With tweet-level attribution, you can:

• Spot your best-performing accounts — see who's consistently sending high-value traffic.
• See ROI at the tweet level — know which specific posts convert, not just which ones get clicks.
• Track campaigns properly — follow a hashtag push or social promo through to real traffic and revenue numbers.

How it works

Convrs continuously scans X for links to your site and ties the resulting traffic and revenue back to the tweet that sent it. To see it in action:

1. Open the Referrers card on your main dashboard.
2. Add an X filter to isolate that traffic.

There are two ways Convrs attributes X traffic:

1. Posts that link to your site

Any time someone tweets a link to your website, Convrs picks it up automatically — nothing to configure.

2. Link-in-bio attribution

If your site is linked in an X profile's bio (yours, a teammate's, or an affiliate's), add that handle so Convrs can attribute the traffic it sends:

1. Go to Settings → Integrations.
2. Find the Twitter / X card.
3. Click the Link attribution tab.
4. Add the handle(s) that link to your site, e.g. @convrsdev.

Only add accounts that genuinely have your website link in their profile — your own account, or a trusted affiliate account. Attribution for existing traffic and revenue can take a few hours to backfill once you add a handle.

Go further

Once you know which tweets are driving results, pair this with X mentions tracking to catch every mention of your brand and product — even the ones that aren't linking directly to your site yet.

Stripe Revenue Attribution

Connect Stripe with Convrs to attribute revenue back to the campaigns, traffic sources, and visitors that generated it.

Once connected, Convrs automatically links successful payments to the original visitor and session, allowing you to see which channels, campaigns, and pages generate revenue.

How It Works

1. A visitor lands on your website.
2. Convrs assigns a unique visitor and session ID.
3. You pass those IDs to Stripe when creating a checkout session or payment intent.
4. Stripe sends the payment data to Convrs.
5. Convrs attributes revenue to the original visitor, campaign, and traffic source.

Required Metadata

When creating a payment, include the following metadata:

These values allow Convrs to connect a Stripe payment to the visitor who originally started the journey.

Stripe Checkout

If you're using Stripe Checkout, include the Convrs identifiers in the checkout session metadata.

const session = await stripe.checkout.sessions.create({
  line_items: [
    {
      price: "price_123",
      quantity: 1,
    },
  ],

  mode: "payment",

  success_url: "https://yourapp.com/success",
  cancel_url: "https://yourapp.com/cancel",

  metadata: {
    convrs_visitor_id: visitorId,
    convrs_session_id: sessionId,
  },
});

Payment Intents

For custom checkout flows, pass the identifiers when creating the payment intent.

const paymentIntent =
  await stripe.paymentIntents.create({
    amount: 5000,
    currency: "usd",

    metadata: {
      convrs_visitor_id: visitorId,
      convrs_session_id: sessionId,
    },
  });

Getting Visitor Information

If you're using the Convrs SDK, retrieve the tracking identifiers before creating the checkout session.

const tracking =
  convrs.getTrackingParams();

console.log(tracking);

Example response:

{
  visitorId: "visitor_123",
  sessionId: "session_456"
}

Recommended Flow

Visitor arrives
       ↓
Convrs creates visitor + session
       ↓
User starts checkout
       ↓
Pass IDs to Stripe metadata
       ↓
Payment succeeds
       ↓
Revenue appears in Convrs

Verify Revenue Attribution

After a successful payment, open your Convrs dashboard and navigate to:

Revenue Attribution → Payments

You should see:

• Revenue amount
• Customer information
• Original traffic source
• Campaign attribution
• Landing page
• Visitor journey

Revenue attribution works for one-time payments, subscriptions, upgrades, and renewals as long as the Convrs identifiers are included in the Stripe metadata.

API Reference

The Convrs Public API gives your scripts, CLI tools, backends, or AI agents read access to the same analytics and revenue data shown in your Convrs dashboard — computed by the exact same query layer, so the numbers always match what you see in the app.

This is the server-side REST API (/api/v1/...), authenticated with a Bearer token. It's a different thing from the client-side tracking SDK (convrs.track(), convrs.identify(), etc.) used to instrument your website.

Base URL

https://convrs.dev/api/v1

Every endpoint on this page and the following pages is relative to this base URL.

API Version

The current (and only) version is v1. Endpoints are versioned in the URL path (/api/v1/...). Breaking changes to response shapes or parameter semantics won't be made to v1 casually — a new version would be introduced instead.

Authentication

Every request requires an Authorization header with a Bearer token:

curl https://convrs.dev/api/v1/account \
  -H "Authorization: Bearer cvrs_..."

See Authentication for the full token format, how to create a token, and scopes.

Bearer Token Format

Tokens are created from Settings → API Tokens in your Convrs workspace and start with the cvrs_ prefix:

cvrs_xxxxxxxxxxxxxxxxxxxxxxxx

Never put a token in a URL or query string — it must be sent in the Authorization header.

API Token Scopes

Each token is granted one or more scopes that gate which endpoints it can call — for example analytics.read, goals.read, and payments.read. See Authentication for the full list and which scope each endpoint requires.

Workspace / Website Scope

A token is created inside one workspace and can only ever read that workspace's data — Convrs currently has no concept of a token spanning multiple websites. Every response is scoped to the token's own website automatically; you never need to (and cannot) select a different one. See Authentication for details.

Rate Limits

Requests are limited to 60 per minute per token. Exceeding the limit returns 429 rate_limit_exceeded. See Rate Limits.

Pagination

List endpoints return a consistent { data, pagination } envelope with page, limit, and hasMore. See Pagination for defaults, maximums, and per-endpoint notes.

Common Query Parameters

Most analytics endpoints share the same date-range, timezone, and website-scoping parameters:

Most analytics endpoints also accept a shared set of filters (country, device, referrer, UTM parameters, etc.) — see Analytics for the full list, since not every endpoint supports every filter (documented per-endpoint).

Error Handling

Every error response uses the same envelope:

{
  "error": {
    "code": "forbidden",
    "message": "This token does not have the required scope: analytics.read"
  }
}

See Errors for the full list of codes and when each occurs.

OpenAPI Reference

A machine-readable OpenAPI 3.1 specification is generated directly from the same validation schemas that power the API, so it can't drift from the real implementation:

https://convrs.dev/api/v1/openapi.json

Use it to import the API into Postman/Insomnia, generate a typed client, or drive AI-agent tool calling.

All API Resources

Metadata Endpoint

GET /api/v1/meta

Returns the metrics, dimensions, and this website's real goal catalogue that the rest of the API actually supports — useful for building a UI or an AI-agent tool schema against the API without hardcoding assumptions.

Authentication: Bearer token · Scope: analytics.read

curl https://convrs.dev/api/v1/meta \
  -H "Authorization: Bearer cvrs_..."

Response:

{
  "data": {
    "intervals": ["24h", "7d", "30d", "90d", "1y", "mtd", "qtd", "ytd"],
    "analytics": {
      "metrics": ["visitors", "new_visitors", "returning_visitors", "bounce_rate", "avg_session_duration", "conversion_rate", "revenue_per_visitor", "revenue", "mrr", "new_revenue", "refund_amount"]
    },
    "breakdowns": {
      "pages": { "metrics": ["visitors", "conversions", "revenue", "revenue_per_visitor", "conversion_rate"], "dimensions": ["page", "hostname", "entrypage", "exitlink"] },
      "sources": { "metrics": ["visitors", "conversions", "revenue", "revenue_per_visitor", "conversion_rate"], "dimensions": ["referrer", "referrer_url", "utm_source", "utm_medium", "utm_campaign", "utm_term", "utm_content", "campaign"] },
      "geo": { "metrics": ["visitors", "conversions", "revenue", "revenue_per_visitor", "conversion_rate"], "dimensions": ["country", "region", "city", "continent"] },
      "devices": { "metrics": ["visitors", "conversions", "revenue", "revenue_per_visitor", "conversion_rate"], "dimensions": ["device", "browser", "os"] }
    },
    "revenue": {
      "metrics": ["revenue", "mrr", "new_revenue", "refund_amount", "revenue_per_visitor", "conversion_rate"]
    },
    "bots": {
      "breakdowns": ["count", "timeseries", "providers", "top_pages", "categories"],
      "categories": ["answer_agent", "index_crawler", "training_crawler", "other"]
    },
    "goals": ["signup", "purchase"]
  }
}

goals is your website's actual, current goal catalogue (event names you've tracked), not a static list.

API Authentication

Bearer Tokens

Every request to /api/v1/... must include an Authorization header:

curl https://convrs.dev/api/v1/account \
  -H "Authorization: Bearer cvrs_..."

• Tokens are Bearer tokens — never pass them as a query parameter or in the request body.
• New tokens are prefixed cvrs_. Tokens created before the public API existed use a legacy bc_ prefix and continue to work.
• A missing or malformed Authorization header, or an invalid token, returns 401 unauthorized.

Creating a Token

API tokens are created, named, and revoked from Settings → API Tokens inside your Convrs workspace. There is no way to create, list, or revoke a token through the API itself — token management is intentionally dashboard-only, so a leaked token can never be used to mint or revoke other tokens.

The full token value is shown exactly once, at creation time. Convrs stores only a one-way hash of it afterward — if you lose it, revoke it and create a new one.

Scopes

A token is granted one or more scopes when it's created. A request fails with 403 forbidden if the token doesn't have the scope an endpoint requires.

Each endpoint's documentation states the exact scope it requires. apis.all satisfies any scope requirement; apis.read satisfies any scope ending in .read.

Website Scope

A token is created inside — and permanently bound to — exactly one workspace (Convrs's tenant/website boundary). There is currently no concept of an account-level token that can read multiple websites.

Some endpoints accept an optional websiteId query or path parameter for symmetry with other APIs. If you pass one, it must match the website your token is scoped to:

• Omitted → the request is automatically scoped to your token's website.
• Matches your token's website → works normally.
• Doesn't match (a different, or made-up, website ID) → 403 forbidden. The mismatch is rejected outright; it is never silently ignored or used to widen access to another website's data.

Revoked and Expired Tokens

• A revoked (deleted) token is rejected the same way an invalid token is: 401 unauthorized. There's no way to distinguish "token never existed" from "token was revoked" in the response — this is intentional, to avoid leaking information about token history.
• An expired token (if an expiry date was set when it was created) is rejected with 401 unauthorized.

Insufficient Scope

If your token is valid but lacks the required scope for an endpoint, you'll get 403 forbidden with a message naming the missing scope:

{
  "error": {
    "code": "forbidden",
    "message": "This token does not have the required scope: payments.read"
  }
}

Security Guidance

• Never expose a token in client-side code, a public repository, or a URL. Treat it as a credential, not a public identifier.
• Never commit a token to source control. Store it in an environment variable or secrets manager.
• Revoke a token immediately from Settings → API Tokens if it may have leaked — revocation takes effect immediately.
• Grant the narrowest scope that does the job. A token that only needs to read analytics doesn't need payments.read.

API Errors

Error Envelope

Every error response — regardless of endpoint or status code — uses the same shape:

{
  "error": {
    "code": "not_found",
    "message": "Customer not found."
  }
}

code is a stable, machine-readable string. message is a human-readable explanation and may change wording over time — don't match on it, match on code.

Status Codes

These are the error codes the public API actually returns:

Notes

• A 401 doesn't distinguish between "token never existed" and "token was revoked" — both return the same generic message, to avoid leaking information about token history.
• A 404 for a customer or funnel ID from a different website looks identical to a 404 for an ID that never existed at all — the API never confirms or denies that a resource exists outside your own website.
• 400 validation errors include a specific message naming the offending parameter, e.g. `startAt` must be before `endAt`. or Metric \mrr` is not available on this endpoint.`

Pagination

Response Format

List/breakdown endpoints return a data array alongside a pagination object:

{
  "data": [ ],
  "pagination": {
    "page": 1,
    "limit": 100,
    "hasMore": true
  }
}

Endpoints that return a single object (like Analytics overview or Account) just return { "data": { ... } } with no pagination key.

Parameters

How hasMore Is Computed

To avoid running an expensive COUNT query on every request, most endpoints fetch limit + 1 rows and set hasMore: true if that extra row exists — hasMore tells you whether there's a next page, not the total row count. There is no totalCount/totalPages field.

Endpoints With Pagination

page/limit pagination applies to: Analytics breakdowns (pages, sources, geo, devices), bot-traffic breakdowns, Goals list, Goal properties, Customers list, Payments, and Funnels list.

One Exception: GET /api/v1/customers

GET /api/v1/customers only accepts a limit parameter (default 100, max 500) — there's no page parameter. Its hasMore is a heuristic (returned rows === limit), not derived from a limit + 1 fetch. If you need to page through more than 500 customers, this endpoint doesn't currently support that — see Customers for details.

Non-Paginated Endpoints

GET /api/v1/analytics/timeseries, GET /api/v1/analytics/revenue/timeseries, and GET /api/v1/analytics/goals return a plain array of time-bucketed points with no pagination — the number of points is bounded by your date range and interval, not by limit.

Rate Limits

Limit

Each API token is limited to 60 requests per minute, counted in a fixed 60-second window per token — one customer's script or agent can't starve another's.

The 429 Response

Exceeding the limit returns:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Too many requests. Please slow down and retry later."
  }
}

Retry-After is in seconds until the current window resets. These headers are only present on a 429 response — successful responses don't currently include rate-limit headers, so don't rely on X-RateLimit-Remaining to preemptively back off; handle 429 and retry after the given delay instead.

Practical Guidance

• Prefer fewer, broader requests over many narrow ones — e.g. request several metrics in one call to /api/v1/analytics instead of one request per metric.
• If you're polling /api/v1/analytics/realtime, a 5–10 second interval is more than enough — the underlying data itself only updates on a similar cadence.
• Cache responses where the data doesn't need to be second-fresh (most analytics and revenue breakdowns).

Account

Get Account

GET /api/v1/account

Verifies your token works and returns basic authenticated context: who created the token, which website it's scoped to, the token's own name and scopes, and the website's plan status. Useful as a first call to confirm a token is valid before wiring up anything else.

Authentication: Bearer token · Scope: none — any valid, non-expired token can call this regardless of which scopes it was granted.

Parameters

None.

cURL

curl https://convrs.dev/api/v1/account \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch("https://convrs.dev/api/v1/account", {
  headers: { Authorization: "Bearer cvrs_..." },
});
const { data } = await res.json();
console.log(data.website.name, data.plan.status);

Response

{
  "data": {
    "user": {
      "id": "usr_...",
      "name": "Jane Doe",
      "email": "jane@example.com"
    },
    "website": {
      "id": "ws_...",
      "name": "Acme Inc",
      "domain": "acme.com"
    },
    "token": {
      "name": "My integration",
      "scopes": ["analytics.read", "goals.read"]
    },
    "plan": {
      "plan": "growth",
      "planFamily": "growth",
      "status": "active"
    }
  }
}

Errors

401 unauthorized (missing/invalid/expired/revoked token). No scope is required, so 403 never occurs on this endpoint.

Websites

Convrs doesn't have a separate "website" object internally — a workspace is a website (one tracked domain per workspace). These endpoints reshape your workspace into that public "website" resource; every field below is a real workspace field, not invented data.

List Websites

GET /api/v1/websites

Lists the websites this token can access. Because a token is bound to exactly one workspace, this always returns a single-item array today — there's no multi-website token in Convrs (see Authentication).

Authentication: Bearer token · Scope: websites.read

cURL

curl https://convrs.dev/api/v1/websites \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch("https://convrs.dev/api/v1/websites", {
  headers: { Authorization: "Bearer cvrs_..." },
});
const { data } = await res.json();

Response

{
  "data": [
    {
      "id": "ws_abc123",
      "name": "Acme Inc",
      "domain": "acme.com",
      "timezone": "America/New_York",
      "currency": "USD",
      "createdAt": "2026-01-15T00:00:00.000Z",
      "plan": "growth",
      "planFamily": "growth",
      "cookielessMode": false,
      "status": "active"
    }
  ]
}

Errors

401 unauthorized, 403 forbidden (missing websites.read scope).

Get Website

GET /api/v1/websites/:websiteId

Gets one website by ID. :websiteId must match the website your token is scoped to — a different or made-up ID returns 403 forbidden, never another website's data.

Authentication: Bearer token · Scope: websites.read

Path Parameters

cURL

curl https://convrs.dev/api/v1/websites/ws_abc123 \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch("https://convrs.dev/api/v1/websites/ws_abc123", {
  headers: { Authorization: "Bearer cvrs_..." },
});
const { data } = await res.json();

Response

Same shape as one item from the list above, but as a single object (data is not an array).

Errors

401 unauthorized, 403 forbidden (missing scope, or websiteId doesn't match your token's website).

Analytics

Core visitor analytics: an overview snapshot, a timeseries, four dimension breakdowns, realtime, and Convrs's AI-crawler/bot-traffic detector. All of these are backed by the exact same query layer the Convrs dashboard uses — the numbers you get here always match the dashboard for the same website and date range.

Authentication: Bearer token · Scope: analytics.read for every endpoint on this page.

Metrics

Each endpoint below states exactly which of these it supports. Request a subset with ?metrics=visitors,revenue; omit metrics to get all of that endpoint's supported metrics (except mrr, which is opt-in only — see Revenue).

Filters

These filters are accepted by the overview, timeseries, and all four dimension-breakdown endpoints (not by realtime or bots — see those sections). Each accepts a single value, a comma-separated list, or an exclusion prefixed with -:

Plus the shared websiteId/interval/startAt/endAt/timezone parameters from the overview.

Overview

GET /api/v1/analytics

A single composite snapshot for one date range.

Query Parameters

cURL

curl "https://convrs.dev/api/v1/analytics?interval=30d&metrics=visitors,revenue" \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch(
  "https://convrs.dev/api/v1/analytics?interval=30d&metrics=visitors,revenue",
  { headers: { Authorization: "Bearer cvrs_..." } }
);
const { data } = await res.json();
console.log(data.visitors, data.revenue);

Response

{
  "data": {
    "visitors": 4213,
    "revenue": 128500
  }
}

data contains exactly the metrics you requested (or all supported metrics, if metrics was omitted), keyed by metric name.

Errors

400 bad_request (invalid metric, invalid date range), 401 unauthorized, 403 forbidden (missing scope, or websiteId mismatch).

Timeseries

GET /api/v1/analytics/timeseries

The same composite metrics as the overview, grouped into a time series. Bucket granularity (hour/day/month) is chosen automatically from the date range's length, matching the dashboard.

Query Parameters

Same as Overview.

cURL

curl "https://convrs.dev/api/v1/analytics/timeseries?metrics=visitors,revenue&interval=day&startAt=2026-09-01&endAt=2026-09-15" \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch(
  "https://convrs.dev/api/v1/analytics/timeseries?metrics=visitors,revenue&startAt=2026-09-01&endAt=2026-09-15",
  { headers: { Authorization: "Bearer cvrs_..." } }
);
const { data } = await res.json();

Response

{
  "data": [
    { "date": "2026-09-01T00:00:00.000Z", "visitors": 120, "revenue": 4200 },
    { "date": "2026-09-02T00:00:00.000Z", "visitors": 98, "revenue": 3100 }
  ]
}

data is a plain array (no pagination) — one object per bucket, with date (ISO 8601 timestamp for the start of the bucket) plus each requested metric.

Errors

Same as Overview.

Pages

GET /api/v1/analytics/pages

Breakdown by page, hostname, entry page, or exit link.

Query Parameters

cURL

curl "https://convrs.dev/api/v1/analytics/pages?dimension=page&limit=50" \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch(
  "https://convrs.dev/api/v1/analytics/pages?dimension=page&limit=50",
  { headers: { Authorization: "Bearer cvrs_..." } }
);
const { data, pagination } = await res.json();

Response

{
  "data": [
    { "page": "/pricing", "visitors": 812, "conversions": 40, "revenue": 9200, "revenue_per_visitor": 11.33, "conversion_rate": 4.9 }
  ],
  "pagination": { "page": 1, "limit": 50, "hasMore": false }
}

The dimension field's key matches whichever dimension you requested (page, hostname, entrypage, or exitlink).

Errors

400 bad_request (invalid dimension, invalid metrics, invalid limit), 401 unauthorized, 403 forbidden.

Sources

GET /api/v1/analytics/sources

Breakdown by referrer or UTM parameters.

Query Parameters

cURL

curl "https://convrs.dev/api/v1/analytics/sources?dimension=utm_source" \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch(
  "https://convrs.dev/api/v1/analytics/sources?dimension=utm_source",
  { headers: { Authorization: "Bearer cvrs_..." } }
);
const { data } = await res.json();

Response

{
  "data": [
    { "utmSource": "newsletter", "visitors": 340, "conversions": 12, "revenue": 2100, "revenue_per_visitor": 6.18, "conversion_rate": 3.5 }
  ],
  "pagination": { "page": 1, "limit": 100, "hasMore": false }
}

The dimension key varies by dimension: referrer, referrerUrl, utmSource, utmMedium, utmCampaign, utmTerm, utmContent, or campaign.

Errors

Same as Pages.

Geo

GET /api/v1/analytics/geo

Breakdown by country, region, city, or continent.

Query Parameters

cURL

curl "https://convrs.dev/api/v1/analytics/geo?dimension=country" \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch(
  "https://convrs.dev/api/v1/analytics/geo?dimension=country",
  { headers: { Authorization: "Bearer cvrs_..." } }
);
const { data } = await res.json();

Response

{
  "data": [
    { "country": "US", "visitors": 1500, "conversions": 60, "revenue": 15000, "revenue_per_visitor": 10, "conversion_rate": 4 }
  ],
  "pagination": { "page": 1, "limit": 100, "hasMore": false }
}

dimension=region rows also include country; dimension=city rows include both country and region.

Errors

Same as Pages.

Devices

GET /api/v1/analytics/devices

Breakdown by device type, browser, or OS.

Query Parameters

cURL

curl "https://convrs.dev/api/v1/analytics/devices?dimension=browser" \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch(
  "https://convrs.dev/api/v1/analytics/devices?dimension=browser",
  { headers: { Authorization: "Bearer cvrs_..." } }
);
const { data } = await res.json();

Response

{
  "data": [
    { "browser": "Chrome", "visitors": 2900, "conversions": 110, "revenue": 21000, "revenue_per_visitor": 7.24, "conversion_rate": 3.8 }
  ],
  "pagination": { "page": 1, "limit": 100, "hasMore": false }
}

Errors

Same as Pages.

Realtime

GET /api/v1/analytics/realtime

Live visitor count, current pages, referrers, countries, and geo points for a realtime map. This endpoint reflects "right now" — it has no date-range parameters.

Query Parameters

None.

cURL

curl https://convrs.dev/api/v1/analytics/realtime \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch("https://convrs.dev/api/v1/analytics/realtime", {
  headers: { Authorization: "Bearer cvrs_..." },
});
const { data } = await res.json();

Response

{
  "data": {
    "count": 8,
    "pages": [{ "page": "/pricing", "count": 3 }],
    "points": [{ "id": "abc-40.7128|-74.0060", "latitude": 40.7128, "longitude": -74.006, "value": 3 }],
    "referrers": [{ "source": "google.com", "count": 5 }],
    "countries": [{ "country": "United States", "code": "US", "count": 6 }]
  }
}

Errors

401 unauthorized, 403 forbidden.

Bots

GET /api/v1/analytics/bots

Convrs's AI-crawler / bot-traffic detector: which AI bots and crawlers are hitting your site, broken down by vendor, category, or page.

Query Parameters

cURL

curl "https://convrs.dev/api/v1/analytics/bots?breakdown=categories" \
  -H "Authorization: Bearer cvrs_..."

JavaScript

const res = await fetch(
  "https://convrs.dev/api/v1/analytics/bots?breakdown=categories",
  { headers: { Authorization: "Bearer cvrs_..." } }
);
const { data } = await res.json();

Response

breakdown=count (default) — a single overview object:

{
  "data": {
    "total_requests": 4200,
    "ai_answers": 1800,
    "indexing": 1500,
    "training": 700,
    "other": 200,
    "unique_providers": 9
  }
}

breakdown=timeseries — a plain array, one object per bucket with one key per bot vendor seen:

{
  "data": [
    { "start": "2026-09-01T00:00:00.000Z", "gptbot": 40, "claudebot": 12 }
  ]
}

breakdown=providers / top_pages / categories — a paginated array, e.g. for providers:

{
  "data": [{ "vendor": "GPTBot", "category": "training_crawler", "requests": 900 }],
  "pagination": { "page": 1, "limit": 100, "hasMore": false }
}