Get started

Domain ownership: verify your domain

On this page

A domain belongs to the account that proves it controls the website. Adding a domain to a site doesn't make it yours; verifying it does. Most sites are verified automatically, without you doing anything.

How verification works

A site verifies a domain in one of three ways. The first that works counts.

MethodHow
Page check (automatic)When your site starts receiving visits from a domain nobody has verified yet, MetricRaven loads https://your-domain/ in the background and looks for your site ID (ana_pub_…) in the HTML. The install script carries it as data-website-id, so a normal install verifies itself within minutes. Installed through Google Tag Manager? When the page loads a GTM container (the official GTM snippet), we also read that container's public file at googletagmanager.com and look for your site ID there, so a GTM install verifies itself too. If it isn't found, we try again at most every 6 hours while visits keep arriving (every 10 minutes during a free trial).
DNS TXT recordFor installs the page check can't see: other tag managers, server-side GTM, or a home page that blocks our checker. Add a TXT record named _metricraven.your-domain with the value shown in Settings → General → Site → Verify (it looks like metricraven-site-verification=…), then choose Check now.
Managed proxyAn active managed proxy on a subdomain of the domain counts as proof: its CNAME can only be added by whoever controls the domain's DNS.

Settings → General → Site shows each domain as Verified (with the method), Not verified or Locked. Admins and the owner can open Verify on a domain that isn't verified to see the TXT record and run a check right away. Checks are limited to a few per website every 10 minutes.

  1. Install the script on your home page

    Follow Install & verify. Once a visit arrives, the page check runs on its own.

  2. Another tag manager, or the check can't reach your page? Add the TXT record

    Open Settings → General → Site, choose Verify next to the domain, copy the name and value into a TXT record at your DNS provider and choose Check now. DNS changes can take a few minutes to show.

What the page check fetches

  • Only https://your-domain/ (or https://www.your-domain/ when the bare domain doesn't answer), on port 443, with the user agent MetricRavenVerifier/1.0.
  • At most 3 redirects, and only within the domain and its www. variant. At most 1 MB is read, with a 5-second timeout. No cookies or credentials are sent.
  • Addresses that aren't on the public internet (private networks, loopback, link-local) are never fetched.
  • When the page loads Google Tag Manager, up to 3 of its containers from https://www.googletagmanager.com/gtm.js?id=GTM-… (at most 3 MB, 8-second timeout). Only container IDs in the official GTM snippet or loader URL count, not one merely written in the page's text.

If your firewall or bot protection blocks unknown agents, allow MetricRavenVerifier or use the DNS record instead.

Adding a domain someone else has

You can add any domain that no other account has verified, from the home page, Add a site, Settings → General → Site, the API, MCP or CLI. Several accounts can list the same domain while nobody has verified it. A domain another account verified can't be added: the answer is 409 domain_taken ("verified by another MetricRaven account"). If you work on that website, ask its owner to invite you (Settings → Team), or add the site with its secret key under Add an existing site. MetricRaven never tells you which account verified it.

Domains are compared without www., case or port. Subdomains follow one rule: the most specific verified domain wins its hosts.

  • Verifying example.com covers its subdomains: another account can't add app.example.com (409 domain_taken, naming example.com), and sites that already list one are locked like copies of the domain itself.
  • A subdomain verified on its own stays with whoever verified it, even if another account later verifies the parent. That account can still add deeper subdomains such as api.app.example.com.
  • Listing a parent of someone else's verified subdomain is allowed (you may own example.com while an agency verified app.example.com), but that site doesn't collect from the verified subdomain or below it: those events get 403 domain_locked. Settings → General → Site lists such subdomains under the domain, without saying who verified them. Everything else under the domain is collected as usual.

During the free trial

A free trial records visits, events, payments and crawler requests only from verified domains (local development on localhost and native apps excepted). Visits from a domain that isn't verified yet are answered with 403 domain_unverified and start a verification check, repeated every 10 minutes while they keep arriving, so recording usually starts within minutes of installing. The install check and Settings → General → Site show when visits are waiting for verification. Each domain gets one free trial: a domain another account already verified needs a plan.

When another account verifies your domain

If your site lists a domain that another account then verifies, your site's copy is locked:

  • Events from that domain are refused for your site (403 domain_locked). Its other domains keep collecting.
  • The dashboard shows a banner with the date, and the owner and admins get one email. Neither names the other account.
  • Remove the domain before that date (the banner's Remove button, or Settings → General → Site) and the site is kept with its reports. If it was the site's only domain, add the domain you do run so it keeps collecting.
  • After 14 days, a site that still lists the locked domain is deleted with all its data, the same way as deleting a website yourself.
Sites in the same account (the same billing owner) are never locked against each other, and demo sites never verify or get locked. If the verifying site later removes the domain or is deleted, the domain is free again and the locks lift.

Weekly re-check

Once a week, each verified domain is checked again with the method that verified it: your site ID on the home page, the TXT record, or an active managed proxy.

  • One failed check changes nothing; we try again every day.
  • After 14 days of failed checks in a row, the owner and admins get one email and the dashboard shows a notice: put the script or record back, or choose Verify again (any of the three methods counts).
  • After 21 days, the domain is released. Your site, its domains and its data stay as they are and nothing is locked or deleted, but another account can then verify the domain.
  • Any successful check ends the streak.

Your domain was verified by someone else

If another account verified your domain and you control the website, choose Verify again on the banner (or on the Locked domain in Settings → General → Site). We check your site's proof and the current owner's proof at that moment:

ResultWhat happens
Yours passes, theirs failsThe domain moves to your site: your lock lifts, and the other account's copy is locked with the usual 14 days, banner and email.
Both passThe domain stays where it is (for example an agency's and a client's script on the same page). Ask that site's owner to invite you.
Yours failsNothing changes. Put the install snippet on your home page, or add the TXT record, then try again.

A domain that just changed hands can't be disputed back for 24 hours. Checks share the limit of Check now. Still stuck? Email support@metricraven.com.

API

EndpointWhat it does
GET /api/v1/site/domains?site=SITE_IDEach domain's state: verified (method, verifiedAt, and failingSince / releaseAfter while re-checks fail), verified_other_site, locked (with deleteAfter) or unverified. Admins and the owner also get the TXT value.
POST /api/v1/site/domains/verify?site=SITE_IDCheck now and Verify again, body { "domain": "example.com" }. result verified, verified_other_site or not_found; on a domain another account verified it is a dispute: transferred, both_verified or not_found, and 409 dispute_cooldown (with retryAfter) within 24 hours of a transfer. 429 rate_limited after 6 checks per website (20 per user) in 10 minutes.
POST /api/v1/site/domains/remove?site=SITE_IDRemoves one domain, body { "domain": "example.com" }. Unlike PUT /api/v1/site it may remove the last domain, which resolves a lock.

These use a dashboard session or an account token (admins and the owner for changes), not the site secret key. See the site API for the rest of the settings.