Domain
Find the domains that rank or buy ads for most of your terms, with how many of their terms you have no page for.
- Price
- 5¢ per 100 rows
- Success rate
- 100% of 2,639 calls
- Freshness
- Fresh for 30 days
- Emits
Domain.competitorsFound- Capability
- Market data
POST https:
Options and prices
Inputs
| Name | Type | Default | Meaning |
|---|---|---|---|
hostname | Hostname | Required | Your domain, or a rival’s to see who it competes with. |
kind | 'organic' | 'paid' | 'organic' | Rivals in the results, or rivals in the ads. |
locale | string | your home Market | The market and language, such as en-US. |
limit | number | 10 | Rivals to return, at most 100, best first. |
maxCost | number | 0.10 | The most this call may spend, in USD. Over it, the call is refused before it spends, or stops early with what it has. |
Outputs
| Field | Type | Unit | What null means |
|---|---|---|---|
competitors | Domain[] | None. | Never null: empty when no domain shares a term, at $0. |
competitors[].hostname | Hostname | None. | Never null. |
competitors[].sharedKeywords | number | terms | Never null: terms you both rank for, or both target. |
competitors[].theirKeywords | number | null | terms in the top 100 | Unknown. |
competitors[].missingForYou | number | null | terms | Unknown: terms they rank for and you do not. |
competitors[].visibility | number | null | 0 to 1, share of clicks on the shared terms | Unknown. |
competitors[] | Observed | None. | Each row also carries observedAt, method and locale. |
basis | 'ranked' | 'targets' | None. | Never null. targets means your domain ranks for too few terms, so rivals were read from the results of your target Keywords instead. |
cost | Cost | USD | Never null. In try mode usd is 0 and maxUsd is what the call would have cost. |
Read the result
| Field | Value | What it means | What to do |
|---|---|---|---|
basis | targets | A new domain ranks for too few terms to have organic rivals; these are the domains on your target terms’ results pages. | Treat them as the rivals for now; run it again once you rank for 50 terms. (the new-domain rule) |
missingForYou | In the hundreds | Most of a rival’s terms are ones you have no page for. | Pass the rival to Keyword.find with exclude set to your domain, and keep the terms under your ceiling. (the content-gap rule in the search playbook) |
visibility | Over 0.3 on your terms | This rival takes about a third of the clicks on the terms you share. | Read their ads with Ad.find and their links with Domain.findLinks first. (our planning number) |
Effects
- Action class
None: it reads, so no approval rule names it
- Modes
try: Runs the read and returns real rows; nothing is saved and nothing is billed.send: Returns a pending Action at once; its Event carries the rows when the read finishes.do: Waits for the read and returns the rows, billed per result.
- Idempotency
The same
Idempotency-Keywith the same input replays the first answer at $0; with other input it returns 409.- Saved or shared
Records each rival as an observed relationship, never as a Domain you hold. Lists are shared across startups for 30 days.
- Emits
Domain.competitorsFoundwith{ competitors,hostname, kind, basis } - Performed by
- Price
About 5¢ per 100 rows. Free: a list younger than 30 days.
maxCostdefaults to 10¢. The top 10 rivals, organic and paid: 20 × 0.05¢ a row is about 1¢.- Reliability
The first route succeeds 100% of 2,639 calls. If it fails, the call refuses with
sources-busyand nothing is spent.- Freshness
A reading younger than 30 days returns at $0. Readings are shared across startups for the same subject and locale.
- Batch and pages
Up to 100 rivals a call. It answers in one response.
- Rate
The shared rate rules: 10 calls a second per key, and an array input counts as one call.
Refuses when
This call has no refusals of its own. Every data call can also meet the shared data-call refusals: filter-unsupported, input-missing, limit-exceeded, max-cost, rate-limited, sources-busy, venue-unsupported.
When it waits
Returns in one response; nothing waits.
Example
Who is leaseline.app up against in search? Spend up to 1¢. To retry, send the same Idempotency-Key: the retry returns the first answer for $0. A new key reads again.
Test values
A sk_test_ key answers these the same way every time, at $0 (every test value).
| Test value | Always returns | What it is for |
|---|---|---|
maxCost: | Refuses with max-cost | Any priced call with a maxCost of 0.0001 is refused before it spends: the price is above the cap. |
rate-limited.test | Refuses with rate-limited | Any call naming this hostname answers 429 with Retry-After, so your retry logic runs. |
sources-busy.test | Refuses with sources-busy | Any call naming this hostname answers 503 as if every route were busy, and nothing is spent. |
Used by
- Workflows: Competitor gap
- Jobs: Size up competitors