Queries and previews

Both /v1/count and /v1/search (root requests) take a query object:

{
  "query": {
    "domain": "example.org",
    "sources_yes": ["a", "b"],
    "sources_no": ["c"]
  }
}

Field	Type	Rules
query.domain	string, required	Exactly one domain, with at most one prefix: none, ^, or *.
query.sources_yes	array of strings, optional	Absent or empty = all sources. Non-empty = whitelist.
query.sources_no	array of strings, optional	Absent or empty = exclude nothing.

Unknown fields anywhere in a request body are rejected with 422 unknown_field — a typo can't silently change your query's meaning.

Domain match modes

Pattern	Meaning	Matches foo.example.org?	Matches evilexample.org?
example.org	the domain itself, or any subdomain (label-aligned)	yes	no
^example.org	the exact domain only	no	no
*example.org	raw string suffix	yes	yes

Warning — the * prefix is a raw suffix match. *example.org also matches unrelated domains that merely end in those characters, such as evilexample.org. This is intentional. Use the no-prefix form for subdomain matching; use ^ when you want exactly one domain.

Source filters

• A source name present in both sources_yes and sources_no → 422 source_in_both_lists.
• An unknown source name in either list → 422 unknown_source.
• sources_no excludes a unit entirely, even when a whitelisted source also holds it. There is no "deliver from the allowed source instead" fallback: exclusion wins.

POST /v1/count — free preview

POST /v1/count
{"query": {"domain": "example.org"}, "max_rows": 1000}

{
  "total_count": 2234,
  "delivered_count": 1000,
  "by_source": {"a": 1000, "b": 100, "c": 1134},
  "est_total_cost_cents": 33971,
  "est_cost_cents": 15206
}

• total_count, delivered_count, and by_source are post-dedup unit counts; by_source covers the full match (cheapest-source attribution) and sums to total_count.
• est_cost_cents prices the delivered subset in expectation — with max_rows absent it equals est_total_cost_cents.
• /v1/count is free and never returns 402; it does validate query shape (422 on malformed queries).
• Counts and cost figures are estimates against live data, not quotes. Run the search to lock in a snapshot.