URL: /docs/api/filters

---
title: Filters
description: Every query parameter of GET /api/v1/domains — the paging trio, the ordering, and the fifteen directory filters.
---

`GET /api/v1/domains` takes three kinds of query parameter: the paging trio, the ordering, and the filters. This page documents all of them. Filtering is free — reading a page never spends a reveal, whatever it matched.

Values are **refused, not ignored**. A parameter listed here, carrying a value it cannot honour, is `400` `invalid_request` naming the parameter and what it accepts. A silently dropped filter would return *more* rows than you asked for, which is a bigger and plausible-looking page with no way to detect it. Parameters not listed here are ignored, so tracking and cache-busting keys are safe to leave on the query string.

## Paging and ordering

Documented in full on [Pagination and sync](/docs/api/pagination).

| Parameter | Type | Notes |
| --- | --- | --- |
| `cursor` | string | Opaque, from the previous response's `next_cursor`. Belongs to the ordering it came from. |
| `limit` | integer | Default 50, maximum 250, minimum 1. Out of range is clamped; a non-integer (including the empty string) is refused. |
| `since` | ISO 8601 instant | **Business plan only** — `402` `upgrade_required` on Free and Pro. Inclusive against `updated_at`. Returns tombstones as well as listings. |
| `sort` | enum: `latest` | Omitted means ascending listing id. `latest` is newest `discovered_at` first. No other value is accepted, and `latest` cannot be combined with `since`. |

## Filters

| Parameter | Type | Filters on |
| --- | --- | --- |
| [`ageMin`](#agemin) | integer 0–100 | Minimum domain age in whole years |
| [`category`](#category) | comma-separated codes | Category |
| [`checkedDays`](#checkeddays) | integer 1–3650 | Availability re-checked within N days |
| [`citabilityMin`](#citabilitymin) | integer 0–100 | Minimum Agent Citability |
| [`featured`](#featured) | boolean | The curated shelf |
| [`priceRange`](#pricerange) | enum | Estimated-value band |
| [`q`](#q) | string, 1–80 chars | Free text — **not** the real name |
| [`rd`](#rd) | comma-separated band ids | Referring-domain band (`lt10`, `10-50`, `50-100`, `100-250`, `250plus`) |
| [`recommended`](#recommended) | boolean | The recommended heuristic |
| [`rsMin`](#rsmin-and-rsmax) | integer 0–100 | Minimum Revised Score |
| [`rsMax`](#rsmin-and-rsmax) | integer 0–100 | Maximum Revised Score |
| [`source`](#source) | comma-separated names | Linking source |
| [`spam`](#spam) | enum: `low`, `moderate` | Spam band ceiling |
| [`tier`](#tier) | enum: `open` | Shelf |
| [`tld`](#tld) | comma-separated TLDs | TLD |

<Warning>
  The `min` filters exclude rows whose value is `null` rather than ranking them low. A `null` metric is absent data, never a zero — an unscored domain is not a DA-0 domain — so `ageMin`, `citabilityMin` and `checkedDays` each drop every row that has no figure. A mild-looking floor can empty most of a page. Each row names its own gaps in `metrics_missing`.
</Warning>

### `ageMin`

Minimum age of the domain in whole years. Integer, 0 to 100.

Rows whose `age_years` is `null` never match, so `ageMin=1` does not mean "at least a year old" — it means "at least a year old **and** the age is known". Age is one of the metrics most often absent, which makes this the filter most likely to cut a shelf harder than intended. Check `metrics_missing` on the rows you do get back.

```bash
curl "https://getrevised.com/api/v1/domains?ageMin=10&limit=50" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

### `category`

One category code, or several comma-separated. Lower case, hyphens — for example `fitness`, `education`, `saas`.

```bash
curl "https://getrevised.com/api/v1/domains?category=saas,education" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

<Note>
  **There is no `/api/v1/categories` endpoint on the REST API**, and an unknown code is **refused**, not answered with an empty page:

  ```json
  { "error": { "code": "invalid_request", "message": "`category` must be a category code — lower case, hyphens, e.g. `fitness`." } }
  ```

  Read codes off the `category` field of a page of results. Over [MCP](/docs/mcp/tools#list_categories) the `list_categories` tool returns the whole vocabulary with labels and counts.
</Note>

There is **no closed list** of codes, and none is published: read them off a page of results rather than guessing. The codes are Revised's own, not a user's words — `marketing` and `software` are not among them. Some listings carry no category at all — they are in the directory and every other filter reaches them, but no `category` value returns them.

### `checkedDays`

Only listings whose availability was re-checked within this many days. Integer, 1 to 3650.

`availability_checked_at` is a stamp, not a live check: reading a listing does not re-check it, and revealing one does. Use this filter when you are about to act on rows and want recent confirmation that the name is still unregistered.

```bash
curl "https://getrevised.com/api/v1/domains?checkedDays=7" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

### `citabilityMin`

Minimum Agent Citability score — how often sources that AI assistants cite link to this domain. Integer, 0 to 100.

Listings with no citability row never match. Absence is not a zero; it means the domain has no row in the current index.

### `featured`

Boolean. Restricts to the curated shelf.

This reads the shelf **rank**, which is not the same thing as the `featured` value of the `tier` field, and the two can disagree. To select by shelf, use `tier`.

### `priceRange`

Estimated-value band. One of:

| Value | Band |
| --- | --- |
| `under-100` | Under `$100` |
| `100-249` | `$100` to `$249` |
| `250-999` | `$250` to `$999` |
| `1000-2499` | `$1,000` to `$2,499` |
| `2500-plus` | `$2,500` and up |

Bucketed on the same figure the response reports as `estimated_value_cents`, so filtering by a band and reading the values back agree. Nothing in the directory is for sale by Revised; this is a valuation, not a price.

### `q`

Free text, 1 to 80 characters.

<Warning>
  `q` searches the masked hint, keyword tags, category and blurb — and **deliberately not the real domain name**. Searching for a name you already have in mind will not find it, whatever your plan and whatever tier the listing is on.

  Use `GET /api/v1/domains/{id}` when you know the id. The tags and the blurb are index-only: they are searchable but are not returned on a row, so a match cannot be explained from the response.
</Warning>

Filter structurally — `category`, `tld`, a metric floor — before reaching for text. Whitespace-only input reads as no search rather than an error.

### `rd`

Referring-domain band, by band **id**. Comma-separate for several. The ids are not the band strings a row reports in `referring_domains` — those contain `<` and `+`, which percent-encode into unreadable URLs.

| Value | Band | Reported on a row as |
| --- | --- | --- |
| `lt10` | Under 10 | `<10` |
| `10-50` | 10 to 50 | `10-50` |
| `50-100` | 50 to 100 | `50-100` |
| `100-250` | 100 to 250 | `100-250` |
| `250plus` | 250 or more | `250+` |

```bash
curl "https://getrevised.com/api/v1/domains?rd=lt10,250plus" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

<Warning>
  Send the **id**, never the value. `?rd=lt10,250plus` works; `?rd=<10,250+` is a `400`. Three of the five ids differ from the string the response reports, so copying a `referring_domains` value straight into the filter fails.
</Warning>

### `recommended`

Boolean. Only listings that pass Revised's own heuristic: a category of any kind (including the literal `other`), at least one recognisable linking site, and a Revised Score floor.

### `rsMin` and `rsMax`

Revised Score bounds, integers 0 to 100. `rsMin` is compared against the **low** end of each listing's published range.

The exact score is not part of the API — `revised_score` is published as a range at every tier, so any two listings are comparable.

```bash
curl "https://getrevised.com/api/v1/domains?rsMin=60&rsMax=85" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

Every listing has a Revised Score, so unlike the other floors this one excludes nothing for being unknown.

### `source`

Linking-source display name. Comma-separate for several. Case is **preserved**, unlike the other list parameters, so send the name as it appears on a row.

These are the recognisable sites that link to a listing — the same values that appear in the `linked_by` array. Observed examples: `Hacker News`, `Wikipedia`, `Medium`, `United Nations`, `Cornell University`, `FCC`. There is no endpoint that enumerates them; read them off `linked_by`.

```bash
curl "https://getrevised.com/api/v1/domains?source=Hacker%20News,Wikipedia" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

### `spam`

Spam band ceiling. One of `low` or `moderate`.

### `tier`

Which shelf. On this endpoint the only accepted value is `open`.

```bash
curl "https://getrevised.com/api/v1/domains?tier=open&limit=250" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

`tier=open` is the cheapest slice of the directory to work with: open names are published on the Revised website anyway, so they arrive populated on every plan, revealing one spends nothing, and they are the only names you may republish. See [Republication](/docs/api/introduction#republication-read-tier-before-you-publish-anything).

A single-value enum rather than a boolean, so the URL says what it selects. Rows come back carrying `tier` values of `open`, `regular` or `featured`; the filter selects `open` only. To select `regular` or `featured`, use the [MCP `search_domains` tool](/docs/mcp/tools#search_domains), whose `tier` argument takes all three.

### `tld`

Exact TLD without the leading dot — `com`, `org`, `com.au`. Comma-separate for several.

```bash
curl "https://getrevised.com/api/v1/domains?tld=com.au,com&rsMin=50" \
  -H "Authorization: Bearer $REVISED_API_KEY"
```

## Comma-separated lists

`category`, `rd`, `source` and `tld` take several values, comma-joined, and match any of them. An item the API cannot read is refused — the response names which item went and what one of that kind has to look like — rather than being dropped from the list.

## Combining filters

Filters combine with AND. Start structural and narrow from there.

```python
import os, requests

BASE = "https://getrevised.com/api/v1"
AUTH = {"Authorization": f"Bearer {os.environ['REVISED_API_KEY']}"}

res = requests.get(
    f"{BASE}/domains",
    headers=AUTH,
    params={
        "tier": "open",          # names disclosed on every plan, republishable
        "tld": "com",
        "rsMin": 60,
        "spam": "low",
        "checkedDays": 30,       # confirmed unregistered in the last month
        "limit": 250,
    },
    timeout=30,
).json()

for row in res["data"]:
    print(row["id"], row["domain"], row["revised_score"], row["referring_domains"])
```

```text Output
00aLaXEG  greenfieldfarms.com  {'low': 61, 'high': 70}  100-500
X00w46xl  tidewaterlabs.com    {'low': 64, 'high': 70}  50-100
```

Every parameter on this page is also in the [OpenAPI document](https://getrevised.com/api/v1/openapi.json), with its JSON Schema constraints.