Concepts: tiers, reveals, holds and banded metrics

This page defines the words the rest of these docs use. It does not tell you how to do anything — the guides do that — and it does not go field by field through the metrics: Metrics explained does.

Listing

A listing is one expired domain in the directory, plus everything Revised knows about it. Every listing has an id: eight characters, case-sensitive, mixed case in practice (00aLaXEG, X00w46xl). Store it verbatim. Lower-casing one will not match on the way back.

A listing is not an offer. Revised does not sell domains. A listing says: this name is not currently registered, here is its link history, go and register it wherever you like if you want it.

Tier — the three shelves

tier is the single most important field on a listing, because it is the only field that tells you whether the name is public.

tier	On the Revised site	May you republish the name?
open	Published — in the listing page’s title and in the sitemap	Yes
regular	Masked	No
featured	Masked; the curated shelf	No

regular and featured names are disclosed to API callers under the API terms only. Republishing rules covers this in full, including the defensive check to put in front of any export.

There is also a featured boolean on each listing. It reads the shelf rank and can disagree with tier == "featured". Branch on tier, never on the boolean.

Masked names

domain holds the registrable name — or null, where the name is withheld. It can be null for two independent reasons, and the field alone cannot tell you which:

1. Another account holds the listing (hold_state: "other"). A hold masks the name for every reader, and having no reveal ceiling is not an exemption. hold_expires_at says when it comes back.
2. You are on Free and have not revealed this listing. Free receives names on the open tier and on anything it already revealed, and a mask on the rest.

On Starter and Business, only reason 1 applies.

mask_hint is populated either way and is what to render: the public partial mask, for example g▓▓▓▓▓▓farms — true length, first letter, last word, hyphens preserved.

name_disclosed is the discriminator for whether you got a real name. mask_hint is not — it is populated on every row whether or not anything is masked.

Reveal

A reveal discloses one masked name and records the listing against your account. It is the only call on the API that spends a reveal: reading a page never charges for the rows it matched.

Where a ceiling applies, reveals are counted in credits: a regular reveal costs 1, a featured reveal costs reveals.featured_credits (1 on Starter and Business), and Free has no reveals.

It is free in two cases, both of which still write a ledger entry: the listing is on the open tier (whose name is published anyway), or your plan has no reveal ceiling. It is idempotent — a repeat returns the original revealed_at and costs nothing. Every first reveal re-checks availability. If the name was registered since our last check, the credit is refunded and the response says so.

A reveal is also a prerequisite: a hold is refused with REVEAL_REQUIRED until reveal has run for the same listing and the same account.

Hold

A hold reserves a listing inside Revised and nothing else. It takes the listing off the shelf for other accounts for a plan-dependent window, and it does not reserve the name on the open internet — registrability out there is not guaranteed, and someone who never used Revised can register it while you hold it.

Holds are account-scoped, not key-scoped. Every key on the account sees, extends and can end the same holds. Who holds a listing is never disclosed to anyone else.

Each hold may be extended exactly once, and the extension runs from where the window was going to end, not from now. A hold ends with an outcome of expired, released or registered.

Banded metrics

The link metrics are published as bands, not numbers:

Field	Example value
referring_domains	"100-250"
backlinks	"1K-5K"
snapshots	"40+"
revised_score	{ "low": 85, "high": 95 } (and revised_score_exact, an integer)

The shapes you have to parse are "10-50", "<100", "250+" and "1K-5K".

This is deliberate. A point estimate implies a precision the underlying link data does not have: a domain measured at 137 referring domains today might measure 119 next week with nothing about the domain having changed. Sorting a shortlist on a fake third significant figure produces a fake ranking.

Flatten bands to a midpoint when you need to sort, keep the band string for display, and never show a midpoint to a reader as if it were a measurement. Evaluating a domain has the parser.

Missing is not zero

null in a metric means Revised has no figure, not a figure of zero. An unscored domain is not a zero-score domain, and agent_citability: null means the domain has no row in the current index — not a score of zero.

The distinction is invisible in JSON, so every listing carries metrics_missing: an array naming exactly which of its optional metrics are absent, by the key they are published under. The candidates are age_years, agent_citability, backlinks and category. An empty array means the row is complete.

Two consequences worth holding on to:

• Filling a missing metric with 0 silently pushes those rows to the bottom of your ranking. That is a judgement you did not intend to make.
• The minimum-value filters (ageMin, citabilityMin, rsMin) exclude null rows rather than ranking them low, so a mild-looking floor can drop most of a page. ageMin=1 means “at least a year old and we know how old it is”, which is not the same question.

Revised Score

revised_score is a published range — {low, high} — for a 0–100 grade blending link-graph centrality, referring domains and site history, computed across the whole directory, plus up to 15 points for real visitor traffic. revised_score_exact carries the integer score itself. rsMin filters on the lower bound of the range. See Metrics explained.

Agent Citability

agent_citability is a preview score for how deeply sources that AI assistants cite link to a domain. It does not predict citation. It carries a score, the linking sources and a basis, and it is null where the domain has no row in the current index. null means not scored, never zero.

The methodology is published in full at getrevised.com/agent-citability.

Spam history

Listings are screened for spam history before they are published, and the directory carries no spam score or band. To screen any name you type, listed or not, start a spam-history check: it classifies the years the web archive captured the name and returns a verdict with its caveats. It is a screen built from archived snapshots, not proof, and an empty history is not a clean one. See Checks on any domain.

Credits

Paid deep checks are priced in credits, separate from reveals. See Credits.

Availability stamp

availability_checked_at records when Revised last checked that the name is unregistered. It is a stamp, not a live check.

A first reveal re-checks it on the spot, on the web and through this API. Reading a page and exports carry the last-checked timestamp instead. Read the age of the stamp before acting on a row, and confirm at a registrar before you register anything. checkedDays filters on stamp freshness.

Estimated value

estimated_value_cents is the valuation model’s low bound, falling back to a reference figure on rows the model has not valued. It is the same number the priceRange filter buckets, so a band and the values it returns agree. Nothing here is for sale, so read it as a signal, not a price.

Categories

A listing’s category is one of Revised’s own codes — saas, education, real-estate and so on. There are 20 of them as of 22 September 2026, and there is no categories endpoint on the REST API; the codes are listed in Finding domains.

An unknown code is refused, not answered with an empty result, which is the behaviour you want: a typo fails loudly. Many listings carry no category at all, and no category filter reaches those.

Cursors, watermarks and tombstones

Paging is by opaque cursor, not offset. A page carries next_cursor and has_more; you pass the cursor straight back. A cursor belongs to the ordering it came from, so keep sort the same across a run, and never construct one — a cursor the endpoint did not issue is a 400, not an empty page.

synced_at on every page is a watermark: the value to pass as since on your next run. It is taken before the page is read and is held 120 seconds behind server time, deliberately, so consecutive polls overlap rather than dropping a row that was mid-commit.

A tombstone is what the since feed returns for a listing that has left the directory: { id, status: "delisted", updated_at } and nothing else. Every row in a feed carries status, so read that before treating a row as a listing. See Incremental sync.

Plans and keys

A key is a bearer token (rvd_...) created at getrevised.com/account. Keys are free on every plan. The key carries no entitlement of its own — the owner’s current plan is resolved on every request.

	Free	Starter	Business
Requests per minute, per key	20	60	120
Reveals	None	No ceiling	No ceiling
Featured reveal	Not allowed	Included	Included
Holds at once	None	5	20
New listings visible after	7 days	Immediately	Immediately
since change feed	No	No	Yes

Every number, with what each one means, is on Plans and limits. Every endpoint answers on every plan. The only thing a plan can be refused outright is the since parameter, which returns 402 upgrade_required on Free and Starter. Read your own numbers from GET /api/v1/me.