API docs

Look up one publisher ID, website, analytics ID or affiliate tag at a time from your own code, with the same access and limits as the dashboard.

The API exists for one job. You have a single thing in hand, a domain, an AdSense publisher ID, an Amazon tag or an analytics ID, and you want to know which sites we've seen it on. You ask about that one thing, you get an answer, you move on. It isn't a way to copy our results in bulk, and our acceptable use policy says so plainly: the API is for looking up one item at a time, not for copying lists.

An API plan is coming soon. Until then, the API works as this page describes: signed in with your account, within your account's limits, with no API keys.

This page documents two endpoints, /lookup and /me. Both answer GET only, and every answer is JSON.

Access

The API answers at https://app.pubsleuth.com/api/v1. There are no API keys yet. Who you are is decided by one thing: whether the request carries the session cookie of a signed-in account.

  • No cookie: you're answered as a signed-out visitor, and your limits are counted against your network address (an IPv4 address, or the /64 block an IPv6 address sits in).
  • The cookie of a signed-in account: you're answered as that account, with its plan if it has one.

In a browser, a signed-in account is the cookie __Secure-authjs.session-token, which the browser sends by itself. It lasts until 30 days after you last use it, and signing out ends it. API keys for scripts are not offered yet, so for now the API is for the dashboard and for light use. We do not describe how to lift a session out of a browser, because a session is a key to your whole account: treat it like a password.

One thing catches people out. An expired or mistyped cookie doesn't produce an error. The request is simply answered as a signed-out visitor, with the smaller limits that go with that. If your answers suddenly say "viewer": "anon", call /me: "signed_in": false means the cookie is no longer good.

Look up an ID or a site

GET https://app.pubsleuth.com/api/v1/lookup?q=<what you're looking up>

There is one parameter, q. You don't say what kind of thing it is: we work that out from its shape, in this order, and the answer tells you what we decided in its kind field.

An AdSense publisher ID
pub- followed by 10 to 20 digits, with or without ca- in front, in any case. kind is pub_id, and the answer lists the sites in AdSense Index that carry the ID.
An analytics or tag-manager ID
UA- with its digits, or G- or GTM- with letters and digits, in any case. kind is tracking_id, and the answer lists the sites in Network Scout that share it.
A website
A bare domain or a whole URL. We drop the scheme, www., any port, path and query. kind is domain, and the answer holds the site's own AdSense publisher IDs (up to three, the largest first, never an ad network's shared account), each with its sites.
An affiliate ID
Anything else: an Amazon tag such as yourtag-20, or a network's publisher ID. kind is affiliate_id, and the answer lists the sites in Affiliate Scout that carry it.

Some worked cases, so the order is clear:

You sendkindRead as
ca-pub-1234567890123456pub_idpub-1234567890123456
g-abc1234xyztracking_idG-ABC1234XYZ
https://www.example.com/blog/?ref=1domainexample.com
yourtag-20affiliate_idyourtag-20
pub-12345affiliate_idToo few digits for a publisher ID
Nothing, or over 200 charactersunknownNot read at all

Something shaped like a domain that ends in -20, -21 or -22 is taken for an Amazon tag, not a website. An empty q, or one over 200 characters, answers "kind": "unknown" with no answers and costs no lookup. Any other text that isn't an ID or a website is read as an affiliate ID and uses one. So a typo still spends a lookup, which is a good reason to check your input before you send it.

What comes back

Here is a signed-out lookup of a made-up publisher ID that nine sites carry. Every domain on this page is an example, not a real site.

{
  "query": "ca-pub-1234567890123456",
  "kind": "pub_id",
  "domain": null,
  "answers": [
    {
      "service": "adsense",
      "id": "pub-1234567890123456",
      "n": 9,
      "shown": [
        { "domain": "slow-cooker-recipes.example", "niche": "Food", "sub_niche": "Recipes" },
        { "domain": "weeknight-dinners.example", "niche": "Food", "sub_niche": "Recipes" },
        { "domain": "bread-baking.example", "niche": "Food", "sub_niche": "Baking" },
        { "domain": "meal-prep-guide.example", "niche": "Food", "sub_niche": "Meal planning" },
        { "domain": "air-fryer-tips.example", "niche": "Food", "sub_niche": "Kitchen appliances" },
        { "domain": "soup-of-the-day.example", "niche": "Food", "sub_niche": "Recipes" }
      ],
      "hidden": 3,
      "network": false,
      "viewer": "anon"
    }
  ]
}

Field by field:

query
What you sent, trimmed.
kind
pub_id, domain, tracking_id, affiliate_id or unknown.
domain
The website as we read it when q was one, otherwise null.
answers
One entry per ID. A single ID gives at most one; a website gives one per publisher ID of its own. Empty when we hold no site on it.
service
adsense, networks or affiliate: which part of pubsleuth answered.
n
Every site we hold on the ID, named to you or not.
shown
The sites named to you, the most visited first.
hidden
Sites counted in n but not named. Their names are never sent.
network
For AdSense answers, true when the ID is an ad network's own account, shared by many unrelated sites, rather than one publisher's. Always false for the other services.
viewer
How you were answered for this service: anon, free or plan.

The same ID asked by a free account names 7 sites and hides 2. Asked by an account whose plan opens AdSense Index, it names all 9, and each row carries the estimates as well:

{ "domain": "slow-cooker-recipes.example", "niche": "Food", "sub_niche": "Recipes",
  "visits": 184000,
  "rev_low": 410, "rev_mid": 820, "rev_high": 1640,
  "top_country": "US", "pub_sites": 9,
  "keywords": ["slow cooker chili", "slow cooker pot roast", "slow cooker soup"] }

visits is estimated monthly visits. rev_low, rev_mid and rev_high are an estimated monthly revenue range in USD. They're estimates and can be wrong, sometimes by a lot, so treat the range as a range. top_country and pub_sites (the number of sites on the site's own publisher ID) come only in AdSense answers. keywords lists up to three of the site's top keywords, and only when we hold them, so don't count on the field being there. Network Scout and Affiliate Scout answers carry visits and the revenue range, and their sub_niche is always null.

Here is how the three kinds of caller differ, for a few sizes of ID:

Sites on the IDSigned out seesFree account seesPlan sees
3333
6566
126712
406740

Signed out, a small ID is shown whole and a larger one keeps at least one site back. A free account sees up to 7. Neither gets the estimates: their rows have domain, niche and sub_niche only. A plan sees every site, up to 500 per answer, with the estimates, but only in the services that plan opens. If you hold the AdSense Explorer plan and look up a G- ID, Network Scout answers you the way it answers a free account, names only, though without the free account's daily cap.

Your usage

GET https://app.pubsleuth.com/api/v1/me

Signed out, the answer is always { "signed_in": false, "services": [] }. Signed in, it's your account and this month's counts. Here is an AdSense Explorer account in the middle of November, with example figures:

{
  "signed_in": true,
  "email": "<your account's email>",
  "services": ["adsense"],
  "usage": { "adsense": { "sites": 1240 } },
  "csv_rows": 300,
  "limits": { "sites_per_month": 10000, "csv_rows_per_month": 1000, "page_max": 100 },
  "resets": "19 November 2026"
}

services lists what your plan opens. usage has a sites count for each of those services: the distinct sites you've been shown this month. csv_rows is what you've exported from the dashboard this month, across all services. limits holds the monthly allowances, plus page_max, the most rows a page of a dashboard list holds. resets is the date the monthly counts start again, in UTC. A free account looks like this:

{ "signed_in": true, "email": "<your account's email>", "services": [], "usage": {}, "csv_rows": 0,
  "limits": { "sites_per_month": 10000, "csv_rows_per_month": 0, "page_max": 100 },
  "resets": "19 November 2026" }

/me costs no lookup, but it counts against the per-minute limit like every call.

Limits

Signed outFree accountPlan
Lookups a day20, per network address50No daily cap
Sites named per answerUp to 6Up to 7Up to 500, in the plan's services
Estimates on each siteNoNoYes, in the plan's services
New sites a monthNo monthly capNo monthly cap10,000 per service
Requests a minute20, burst 1060, burst 3060, burst 30

The daily lookup caps aren't a counter that empties at midnight. They refill gradually over 24 hours. Signed out, you start with 20; spend them all and one comes back every 72 minutes. Leave it alone for six hours and 5 are back. A free account gets one back every 28.8 minutes, so 12 after six hours. A refused lookup doesn't use one up.

The per-minute limit is a bucket with a burst of 10 signed out (per network address) and 30 signed in. Every call takes a token from it, /me and empty lookups included, and it refills at the per-minute rate. Signed in, that means 30 calls at once, then 60 a minute. A refused call still takes a token, down to minus the burst, so a client that keeps calling stays refused longer. CSV export is part of the dashboard (1,000 to 5,000 rows a month by plan). The answers carry no rate-limit headers yet: /me gives a plan's monthly usage; the daily lookups left and the per-minute budget aren't reported yet.

How the month is counted

A plan's monthly cap counts the distinct sites you're shown in each service, per billing period: from one billing date of your plan to the next, whether you saw them in the dashboard, on a lookup page or through the API.

  • Only named sites count. Hidden ones don't, and neither does a lookup that finds nothing.
  • A site counts once a period per service. See it again in the same period and it adds nothing.
  • An answer never names more sites than you have left. With 25 left and an ID carrying 40 sites, you get 25 named and 15 hidden.
  • Once the count reaches 10,000, every lookup in that service answers quota_exceeded until your next billing date, even one for an ID you've already seen.
  • Everything starts again on your plan's billing date: a plan bought on the 19th starts again on the 19th of each month. The date is in /me as resets.

An example, on a plan that renews on the 19th. On 14 November you look up an ID with 40 sites, and your AdSense count goes up by 40. On 17 November you look it up again and three new sites have appeared on it: the count goes up by 3. On 19 November, your billing date, it's back to zero.

Errors

An error answers with its HTTP status and a JSON body with two fields, a code for your program and a sentence for a person:

{ "error": "<code>", "message": "<what happened>" }

These two endpoints answer 200 when all is well, and otherwise one of these:

StatusCodeWhenWhat to do
429lookup_limitSigned out, and today's lookups from your network address are used.Wait: lookups come back one at a time through the day. Or sign in.
429lookup_limit_freeOn a free account, and today's lookups are used.Wait: lookups come back one at a time through the day.
429quota_exceededOn a plan, and this month's new sites in that service are used.Stop asking in that service until your plan's next billing date (resets in /me).
429rate_limitedToo many requests in a short time, on any endpoint.Pause, then carry on more slowly. A minute without calls clears it.
500server_errorSomething went wrong on our side.Try once more a little later. If it keeps happening, tell us.

What the bodies look like (the date in the third is an example):

429 { "error": "lookup_limit",
      "message": "20 lookups a day without an account. A free account looks up 50 a day." }
429 { "error": "lookup_limit_free",
      "message": "50 lookups a day on a free account. A plan looks up without a daily limit." }
429 { "error": "quota_exceeded",
      "message": "You've seen this month's 10,000 AdSense Index sites. Pages of sites you've already opened stay open; lookups and lists in this service stop until your plan's next billing date, when the allowance starts again." }
429 { "error": "rate_limited",
      "message": "Too many requests: slow down and try again in a minute." }
500 { "error": "server_error", "message": "Something went wrong." }

Write your code against error, not message. The sentences are for people, and we may reword them.

When you get a 429

Four different limits answer 429, and they clear on very different clocks, so look at the code before you retry.

  • rate_limited clears in seconds. A signed-in client that has dug the bucket all the way down needs 31 seconds without calls; signed out it's 33 seconds. Waiting a full minute is always enough. Retrying straight away makes it worse.
  • lookup_limit and lookup_limit_free clear one lookup at a time, as described under limits. Retrying in a loop gains nothing.
  • quota_exceeded clears on your plan's next billing date, the resets date in /me. Stop asking in that service.

No answer carries a Retry-After header, so the wait is yours to choose. In JavaScript:

if (res.status === 429) {
  const { error } = await res.json();
  if (error === "rate_limited") await new Promise((r) => setTimeout(r, 60_000));   // then retry once
  else throw new Error(error);   // a daily or monthly limit: retrying now won't help
}

Example calls

The examples below are signed-out calls, which are answered with the signed-out limits. In a browser where you are signed in, the same requests are answered as your account.

curl, letting curl encode a URL as q:

curl --get "https://app.pubsleuth.com/api/v1/lookup" \
  --data-urlencode "q=https://www.example.com/some-page"

JavaScript (Node 18 or later, which has fetch built in):

const res = await fetch(`https://app.pubsleuth.com/api/v1/lookup?${new URLSearchParams({ q: "yourtag-20" })}`);
const body = await res.json();
if (!res.ok) throw new Error(`${res.status} ${body.error}: ${body.message}`);
for (const a of body.answers) console.log(a.id, a.n, a.shown.map((s) => s.domain));

Python, with requests:

import requests

r = requests.get("https://app.pubsleuth.com/api/v1/lookup", params={"q": "G-ABC1234XYZ"}, timeout=30)
body = r.json()
if r.status_code != 200:
    raise RuntimeError(f"{r.status_code} {body['error']}: {body['message']}")
print(body["kind"], [a["n"] for a in body["answers"]])

Freshness and caching

Each service's findings reach the website once a day. Ask about the same ID twice in an afternoon and you get the same answer twice, having spent a lookup, or at least a token, each time. Our answers are sent with Cache-Control: private, no-store, so nothing between you and us keeps a copy. If you want one, keep it in your own code; holding an answer for the rest of the day loses you nothing.

What the API doesn't do

  • No bulk export through these endpoints. Lookups are one item at a time, and spreading them across accounts or addresses to get around the limits breaks the acceptable use policy.
  • No contact details for the people who run websites. pubsleuth holds no email addresses, phone numbers or other contact details for them, so no answer can include them. (/me returns your own account's email, since it is about you.)
  • No keyword volumes. The keywords field names a few keywords where we hold them, with no search volumes. pubsleuth isn't a keyword tool.
  • No API keys, no usage headers and no count of your daily lookups left, yet. An API plan is coming soon.

Good practice

  1. Keep answers for the day. The data won't change before the next daily load.
  2. Back off on 429, and read the code first: a minute for rate_limited, much longer for the others.
  3. Be specific. Send the exact ID or domain you mean: a malformed query still costs a lookup, and a guess is read as an affiliate ID and usually matches nothing.
  4. Check /me now and then rather than counting the month's sites yourself.