Quickstart: search expired domains with the Revised API

By the end of this you will have a working API key, a page of real listings filtered down to names you are free to republish, and one revealed domain. About five minutes.

Prerequisites

• A Revised account (sign up — free).
• curl, or Python 3.9+ with requests.

Everything below works on the free plan.

1. Create an API key

Go to getrevised.com/account and create a key. Keys are free on every plan, including free. Copy the value — it is shown once.

export REVISED_API_KEY=rvd_...

2. Check what your key can do

GET /api/v1/me costs one request and no reveals. Call it first every time: it tells you your plan, your remaining reveals, your rate limit, and whether the change feed is available to you.

curl -s https://getrevised.com/api/v1/me \
  -H "Authorization: Bearer $REVISED_API_KEY"

{
  "plan": "free",
  "reveals": {
    "limit": 0,
    "remaining": 0,
    "used": 0,
    "resets_at": "2026-10-01T00:00:00.000Z",
    "featured_credits": null,
    "rollover": 0
  },
  "rate_limit": { "limit": 20, "remaining": 19 },
  "sync_feed": false,
  "key": {
    "name": "laptop",
    "prefix": "rvd_a1b2c3",
    "created_at": "2026-09-22T01:10:44.000Z",
    "last_used_at": null
  }
}

The response above is an illustration of a Free key — read your own from the call. Three fields matter:

• reveals.limit is null on a plan with no ceiling (Starter and Business), and 0 on Free, which has no reveals. Where reveals are counted, they are in credits: a regular reveal costs 1, and featured_credits is what a featured reveal costs (null means your plan cannot reveal one). On a plan with a ceiling, reveals.remaining is both your budget for reveals and what decides whether an unrevealed listing arrives with its name or with a mask.
• rate_limit.limit is your per-minute ceiling per key: 20 on Free, 60 on Starter, 120 on Business.
• sync_feed is false unless you are on Business. It gates exactly one parameter (since); everything else answers on every plan.

The plan reported here is the owner’s plan, resolved on every request. A lapsed subscription reads as free without anything having revoked the key.

3. Read a page of the directory

Listing is free and unlimited inside your rate limit — a page never charges for the rows it matched. Filter structurally on the server, then narrow locally.

curl -s -G https://getrevised.com/api/v1/domains \
  -H "Authorization: Bearer $REVISED_API_KEY" \
  -d tier=open \
  -d rsMin=70 \
  -d limit=5

{
  "data": [
    {
      "id": "HSBQyXkl",
      "status": "active",
      "domain": "blogbuzz.com.au",
      "tier": "open",
      "name_disclosed": true,
      "tld": "com.au",
      "referring_domains": "10-50",
      "backlinks": "500-1K",
      "revised_score": { "low": 85, "high": 95 },
      "agent_citability": { "score": 65 },
      "snapshots": "<10",
      "linked_from": ["United Nations"],
      "linked_from_count": 1,
      "metrics_missing": ["age_years", "category"],
      "hold_state": "none",
      "estimated_value_cents": 100,
      "availability_checked_at": "2026-09-19T21:04:06.589Z",
      "updated_at": "2026-09-19T21:04:06.589Z"
    }
  ],
  "next_cursor": "c7Kd0Pq1",
  "has_more": true,
  "synced_at": "2026-09-22T03:14:07.000Z"
}

Four things in that response deserve a second look.

1. tier: "open" — this name is already published on the Revised site, so you may republish it. Rows on the regular and featured shelves are not. See Republishing rules.
2. The metrics are bands. "10-50", "500-1K", "<10", and revised_score is a range. That is deliberate; Concepts explains why.
3. metrics_missing names which optional metrics are null on this row. A null is absent data, never a zero.
4. next_cursor is opaque. Pass it straight back as cursor for the next page and stop when has_more is false. Never build one yourself.

4. Reveal a name

POST /api/v1/domains/{id}/reveal is the only call on this API that spends a reveal (a paid deep check spends credits instead). It is free when the listing is on the open tier or your plan has no reveal ceiling. It is idempotent, so a repeat call returns the original revealed_at and costs nothing. Every first reveal also re-checks availability. If the name was registered since our last check, the credit is refunded. The response reports the cost in credits_charged.

Everything you filtered for in step 3 is open tier, so this is free:

curl -s -X POST https://getrevised.com/api/v1/domains/HSBQyXkl/reveal \
  -H "Authorization: Bearer $REVISED_API_KEY"

{
  "id": "HSBQyXkl",
  "domain": "blogbuzz.com.au",
  "tier": "open",
  "name_disclosed": true,
  "revealed_at": "2026-09-22T03:15:02.117Z",
  "availability_checked_at": "2026-09-19T21:04:06.589Z",
  "credits_charged": 0,
  "credits_remaining": 5
}

Listing ids are eight characters and case-sensitive — HSBQyXkl, not hsbqyxkl. Store them verbatim; a lower-cased id will not match on the way back.

5. The same flow in Python

import os

import requests

BASE = "https://getrevised.com"
session = requests.Session()
session.headers["Authorization"] = f"Bearer {os.environ['REVISED_API_KEY']}"

me = session.get(f"{BASE}/api/v1/me", timeout=30).json()
print(me["plan"], me["rate_limit"], me["reveals"])

page = session.get(
    f"{BASE}/api/v1/domains",
    params={"tier": "open", "rsMin": 70, "limit": 5},
    timeout=30,
).json()

for row in page["data"]:
    if row["status"] != "active":
        continue  # a tombstone: the listing has left the directory
    print(row["id"], row["tier"], row["referring_domains"], row["domain"] or row["mask_hint"])

free {'limit': 20, 'remaining': 18} {'limit': 10, 'remaining': 10, 'used': 0, 'resets_at': '2026-10-01T00:00:00.000Z'}
HSBQyXkl open 10-50 blogbuzz.com.au
LxRrd32h open 100-250 septictankcleaningsydney.com.au
qiQVcWts open 250+ bancroftart.com.au
sKBxLozT open 100-250 westernpridefc.com.au
82TJANWQ open 10-50 horriblevacuum.com

What now