Measurement API

Authentication — exchange your org API key for a short-lived token first: POST /v1/auth/api-token with X-API-Key: <your key>, then send the token as Authorization: Bearer <token> on the calls below. The key itself authenticates the platform API; this API keeps its own token table. A key sent straight here is rejected. Both shipped clients do the exchange for you. Base URL: … · Raw spec: openapi.json
Prefer tools over raw HTTP? The same data is exposed to MCP clients via the MCP server below.
Rate limits — 600 requests a minute per API key. Over it, you get a 429 with a Retry-After header; back off that many seconds and continue. Real dashboards and connectors sit far under this.

Install — the package is on npm. One command adds it to Claude Code (for other clients, put the same npx line in claude_desktop_config.json / .mcp.json):

claude mcp add praised \
  --env PRAISED_API_KEY=<your org API key> \
  -- npx -y @praised/mcp-server

# equivalent JSON for any MCP client
{
  "mcpServers": {
    "praised": {
      "command": "npx",
      "args": ["-y", "@praised/mcp-server"],
      "env": { "PRAISED_API_KEY": "<your org API key>" }
    }
  }
}

The key comes from Settings → API keys and is exchanged for a short-lived token behind the scenes. Nothing permanent travels to the measurement API. Every call is scoped to what you can already read and do. Self-hosting? PLATFORM_URL, MEASURE_API_URL and STUDIO_URL point it at your own deployment.

Cloudflare Worker — passthrough proxy; AI-bot hits are reported after the response is served, and it adds zero latency for your visitors:

// wrangler secret put PRAISED_API_KEY   (a key from Settings → API keys)
// Route: yourdomain.com/*
const AI_UA = /(GPTBot|OAI-SearchBot|ChatGPT|Claude|anthropic|Perplexity|Google-Extended|GoogleOther|Bytespider|Meta-ExternalAgent|FacebookBot|Applebot|Amazonbot|CCBot|cohere|DuckAssistBot|YouBot|PetalBot|Diffbot|Timpibot|MistralAI|bingbot|OAI-AdsBot|Google-Agent|Meta-WebIndexer|Meta-ExternalFetcher|Meta-ExternalAds|Amzn-SearchBot|Amzn-User)/i;

export default {
  async fetch(request, env, ctx) {
    const response = await fetch(request);
    const ua = request.headers.get("user-agent") || "";
    if (AI_UA.test(ua)) {
      ctx.waitUntil(fetch("https://api.praised.co/v1/crawler/ingest", {
        method: "POST",
        headers: { "content-type": "application/json", "x-api-key": env.PRAISED_API_KEY },
        body: JSON.stringify({ hits: [{
          user_agent: ua,
          path: new URL(request.url).pathname,
          status: response.status,
          timestamp: new Date().toISOString(),
          ip: request.headers.get("cf-connecting-ip"),   // lets us VERIFY the bot
        }] }),
      }).catch(() => {}));
    }
    return response;
  },
};

The regex is a coarse prefilter: ordinary visitor traffic never leaves your edge — exact bot detection (vendor, purpose: training vs live answers vs search) happens server-side against the maintained registry. Send ip. A User-Agent is a string anyone can type. The address it arrived from is the only thing that can prove the bot was real: we check it against the vendors' published IP ranges and, for Google and Apple, forward-confirmed reverse DNS. Hits with no address are labelled unverifiable — never spoofed, because not checking is not the same as failing. The address is used for that check and then discarded: there is no IP column in the crawler table, and a test fails the build if one is ever added.

Vercel — Edge Middleware, one file (middleware.js) at the project root. Runs before the response. The status isn't known yet — the field is optional and the server records the hit either way. waitUntil keeps it off your visitors' path:

// Set PRAISED_API_KEY in Project Settings → Environment Variables
const AI_UA = /(GPTBot|OAI-SearchBot|ChatGPT|Claude|anthropic|Perplexity|Google-Extended|GoogleOther|Bytespider|Meta-ExternalAgent|FacebookBot|Applebot|Amazonbot|CCBot|cohere|DuckAssistBot|YouBot|PetalBot|Diffbot|Timpibot|MistralAI|bingbot|OAI-AdsBot|Google-Agent|Meta-WebIndexer|Meta-ExternalFetcher|Meta-ExternalAds|Amzn-SearchBot|Amzn-User)/i;

export const config = { matcher: "/:path*" };

export default function middleware(request, context) {
  const ua = request.headers.get("user-agent") || "";
  if (AI_UA.test(ua)) {
    context.waitUntil(fetch("https://api.praised.co/v1/crawler/ingest", {
      method: "POST",
      headers: { "content-type": "application/json", "x-api-key": process.env.PRAISED_API_KEY },
      body: JSON.stringify({ hits: [{
        user_agent: ua,
        path: new URL(request.url).pathname,
        timestamp: new Date().toISOString(),
        ip: (request.headers.get("x-forwarded-for") || "").split(",")[0].trim(),
      }] }),
    }).catch(() => {}));
  }
}

Netlify — an Edge Function (netlify/edge-functions/praised.js). The report is awaited only on bot requests — the regex filter means your visitors' requests never wait on it:

// netlify env:set PRAISED_API_KEY vis_…
const AI_UA = /(GPTBot|OAI-SearchBot|ChatGPT|Claude|anthropic|Perplexity|Google-Extended|GoogleOther|Bytespider|Meta-ExternalAgent|FacebookBot|Applebot|Amazonbot|CCBot|cohere|DuckAssistBot|YouBot|PetalBot|Diffbot|Timpibot|MistralAI|bingbot|OAI-AdsBot|Google-Agent|Meta-WebIndexer|Meta-ExternalFetcher|Meta-ExternalAds|Amzn-SearchBot|Amzn-User)/i;

export default async (request, context) => {
  const response = await context.next();
  const ua = request.headers.get("user-agent") || "";
  if (AI_UA.test(ua)) {
    await fetch("https://api.praised.co/v1/crawler/ingest", {
      method: "POST",
      headers: { "content-type": "application/json", "x-api-key": Netlify.env.get("PRAISED_API_KEY") },
      body: JSON.stringify({ hits: [{
        user_agent: ua,
        path: new URL(request.url).pathname,
        status: response.status,
        timestamp: new Date().toISOString(),
        ip: context.ip,   // lets us VERIFY the bot
      }] }),
    }).catch(() => {});
  }
  return response;
};

export const config = { path: "/*" };

Fastly — real-time log streaming to an HTTPS endpoint. Nothing runs in your visitors' path: Fastly writes each log line after the response and sends only the AI-bot ones, in batches.

1. Register the service with a key from Settings → API keys. Fastly checks that the endpoint lists your service before it sends a line:

   curl -X POST -H "x-api-key: vis_…" https://api.praised.co/v1/crawler/fastly/services/YOUR_SERVICE_ID

2. In the service, Logging → HTTPS: URL https://api.praised.co/v1/crawler/ingest/fastly, method POST, JSON log entry format Newline delimited, custom header x-api-key with the same key, maximum entries 1000 and maximum bytes 1000000 (request bodies are capped at 1 MB).
3. Log format:

   {"user_agent":"%{json.escape(req.http.User-Agent)}V","path":"%{json.escape(req.url.path)}V","status":%>s,"timestamp":"%{begin:%Y-%m-%dT%H:%M:%S}tZ","ip":"%{client.ip}V","host":"%{json.escape(req.http.host)}V","event_id":"%{req.xid}V","response_bytes":%{resp.bytes_written}V,"latency_ms":%{time.elapsed.msec}V}

4. Condition (a response condition on the endpoint), the same prefilter as the other recipes:

   req.http.User-Agent ~ "(?i)(GPTBot|OAI-SearchBot|ChatGPT|Claude|anthropic|Perplexity|Google-Extended|GoogleOther|Bytespider|Meta-ExternalAgent|FacebookBot|Applebot|Amazonbot|CCBot|cohere|DuckAssistBot|YouBot|PetalBot|Diffbot|Timpibot|MistralAI|bingbot|OAI-AdsBot|Google-Agent|Meta-WebIndexer|Meta-ExternalFetcher|Meta-ExternalAds|Amzn-SearchBot|Amzn-User)"

client.ip is the address that connected to Fastly: the one that can prove the bot was real. req.xid names the request, so a batch Fastly retries is counted once.

Amazon CloudFront — a Lambda on the bucket that holds the distribution's standard logs. Each new log file is read, its AI-bot lines are kept and sent; nothing touches your visitors' requests. Logs already in the bucket backfill the same way, from your own machine.

1. Turn on standard logging to S3 for the distribution (legacy or v2, W3C format).
2. Create a Node.js 20 Lambda from the file below. Set PRAISED_API_KEY, give its role s3:GetObject on the log bucket, and add an S3 event notification (object created, on the log prefix) that invokes it.
3. Backfill: aws s3 sync s3://LOG_BUCKET/PREFIX ./cf-logs, then PRAISED_API_KEY=vis_… node praised-cloudfront.mjs ./cf-logs/*.gz.

// praised-cloudfront.mjs: a Lambda on the standard-log bucket, or run by hand to backfill
import { gunzipSync } from "node:zlib";
import { readFileSync } from "node:fs";

const AI_UA = /(GPTBot|OAI-SearchBot|ChatGPT|Claude|anthropic|Perplexity|Google-Extended|GoogleOther|Bytespider|Meta-ExternalAgent|FacebookBot|Applebot|Amazonbot|CCBot|cohere|DuckAssistBot|YouBot|PetalBot|Diffbot|Timpibot|MistralAI|bingbot|OAI-AdsBot|Google-Agent|Meta-WebIndexer|Meta-ExternalFetcher|Meta-ExternalAds|Amzn-SearchBot|Amzn-User)/i;

function parseLog(text) {
  const decode = (s) => { try { return decodeURIComponent(s); } catch { return s; } };
  const num = (s) => (s === undefined || s === "" || s === "-" ? null : Number(s));
  let fields = [];
  const hits = [];
  for (const line of text.split("\n")) {
    if (line.startsWith("#Fields:")) { fields = line.slice(8).trim().split(/\s+/); continue; }
    if (!line.trim() || line.startsWith("#")) continue;
    const v = {};
    line.split("\t").forEach((x, i) => { v[fields[i]] = x; });
    const ua = decode(v["cs(User-Agent)"] || "");
    if (!AI_UA.test(ua)) continue;
    hits.push({
      user_agent: ua,
      path: v["cs-uri-stem"],
      status: v["sc-status"] === "000" ? null : num(v["sc-status"]),  // 000: the viewer left before the answer
      timestamp: `${v.date}T${v.time}Z`,                               // standard logs are UTC
      ip: v["c-ip"],                                                   // lets us VERIFY the bot
      host: v["x-host-header"],                                        // your site's name, not the cloudfront.net one
      event_id: v["x-edge-request-id"],                                // a file read twice is counted once
      response_bytes: num(v["sc-bytes"]),
      latency_ms: v["time-taken"] ? Math.round(Number(v["time-taken"]) * 1000) : null,
    });
  }
  return hits;
}

async function ship(hits) {
  for (let i = 0; i < hits.length; i += 1000) {   // request bodies are capped at 1 MB
    const r = await fetch("https://api.praised.co/v1/crawler/ingest", {
      method: "POST",
      headers: { "content-type": "application/json", "x-api-key": process.env.PRAISED_API_KEY },
      body: JSON.stringify({ hits: hits.slice(i, i + 1000), provider: "cloudfront" }),
    });
    if (!r.ok) throw new Error(`Praised answered ${r.status}`);   // Lambda retries the file
  }
}

export const handler = async (event) => {
  const { S3Client, GetObjectCommand } = await import("@aws-sdk/client-s3");
  const s3 = new S3Client({});
  for (const rec of event.Records) {
    const key = decodeURIComponent(rec.s3.object.key.replace(/\+/g, " "));
    const obj = await s3.send(new GetObjectCommand({ Bucket: rec.s3.bucket.name, Key: key }));
    await ship(parseLog(gunzipSync(await obj.Body.transformToByteArray()).toString("utf8")));
  }
};

// Backfill by hand: node praised-cloudfront.mjs ./cf-logs/*.gz
if (!process.env.AWS_LAMBDA_FUNCTION_NAME && process.argv.length > 2) {
  for (const file of process.argv.slice(2)) await ship(parseLog(gunzipSync(readFileSync(file)).toString("utf8")));
}

Any other host — a nightly cron over your access log. Reads combined-format lines, keeps the AI-bot ones, batches up to 5,000 per request. (The Studio's measure panel also takes the same log as a CSV upload if you'd rather not run anything.)

#!/usr/bin/env node
// PRAISED_API_KEY=vis_… node ship-logs.mjs /var/log/nginx/access.log
import { readFileSync } from "node:fs";

const AI_UA = /(GPTBot|OAI-SearchBot|ChatGPT|Claude|anthropic|Perplexity|Google-Extended|GoogleOther|Bytespider|Meta-ExternalAgent|FacebookBot|Applebot|Amazonbot|CCBot|cohere|DuckAssistBot|YouBot|PetalBot|Diffbot|Timpibot|MistralAI|bingbot|OAI-AdsBot|Google-Agent|Meta-WebIndexer|Meta-ExternalFetcher|Meta-ExternalAds|Amzn-SearchBot|Amzn-User)/i;
// combined log format: ip - - [time] "METHOD /path HTTP/x" status bytes "referer" "user-agent"
// the leading field is the client IP — that is what lets us VERIFY the bot
const LINE = /^(\S+) \S+ \S+ \[([^\]]+)\] "\S+ (\S+)[^"]*" (\d{3}) \S+ "[^"]*" "([^"]*)"/;

const hits = [];
for (const line of readFileSync(process.argv[2], "utf8").split("\n")) {
  const m = LINE.exec(line);
  if (!m || !AI_UA.test(m[5])) continue;
  hits.push({ user_agent: m[5], path: m[3], status: Number(m[4]), ip: m[1] });
}
const BATCH = 1000;   // request bodies are capped at 1 MB; 1,000 hits stays well under
for (let i = 0; i < hits.length; i += BATCH) {
  const r = await fetch("https://api.praised.co/v1/crawler/ingest", {
    method: "POST",
    headers: { "content-type": "application/json", "x-api-key": process.env.PRAISED_API_KEY },
    body: JSON.stringify({ hits: hits.slice(i, i + BATCH) }),
  });
  console.log(`shipped ${Math.min(i + BATCH, hits.length)}/${hits.length} — ${r.status}`);
}

WordPress — a plugin. There is nothing to paste. It records only the requests whose user-agent matches a known AI crawler, queues them in your own database, and sends them every five minutes. Visitor traffic is never stored and never leaves your server; nothing is added to your pages.

Install it, then Settings → Praised: paste a key from Settings → API keys and press Test connection. That records a test hit straight away. You find out in a second rather than waiting days for a real crawl.

One setting matters: Visitor address from. The address a request arrived from is the only thing that can prove a crawler was genuine, and behind a CDN the address your server sees is the CDN's. Pick the source your hosting actually provides — the settings screen shows what it currently resolves to. You can check it against your own address. Getting it wrong makes hits read can't verify, which is honest; the plugin will not read the client-supplied end of X-Forwarded-For, because that would let anyone forge an address inside a vendor's range and manufacture verified traffic in your reports.

Download the plugin · also on the WordPress plugin directory.

The loop this makes possible. Ask your AI tool to "fix my top three visibility findings": it calls list_actions, pulls the exact markup with get_fix, applies it in your repo, then calls mark_action_fixed — which re-audits the live page and reports back whether the finding is genuinely gone. A fix that didn't land comes back as not cleared, with the reason, and the item returns to the queue. The AI tool never gets to mark its own homework.