Keyword.search · SalesBuilder

POST https://api.sb/{your-domain}/keywords/search

Options and prices

You get	Input that selects it	Price	Success rate
Google results and your rank	`{"venue":"google-search"}`	About 3¢ per 100 searches	99.1% of 1,710,120 calls
Bing results	`{"venue":"bing"}`	About 3¢ per 100 searches	90.7% of 5,169 calls
Local results around a place	`{"venue":"google-maps","place":"Tacoma, WA"}`	About 10¢ per 100 searches	99.5% of 223,694 calls
News results	`{"venue":"google-news"}`	About 10¢ per 100 searches	99.95% of 301,427 calls
Posts on Reddit	`{"venue":"reddit"}`	About 19¢ per 100 searches	99.4% of 142,199 calls
Posts on X	`{"venue":"x"}`	About 8¢ per 100 searches	85.6% of 162,439 calls
Posts on Hacker News	`{"venue":"hacker-news"}`	About 2¢ per 100 searches	100% of 1,200 calls
Posts on LinkedIn	`{"venue":"linkedin"}`	About 20¢ per 100 searches	99.97% of 154,260 calls
Posts on YouTube	`{"venue":"youtube"}`	About 9¢ per 100 searches	100% of 9,400 calls
Posts on TikTok	`{"venue":"tiktok"}`	About 12¢ per 100 searches	99.99% of 64,000 calls
Posts on Stack Overflow	`{"venue":"stack-overflow"}`	About 1.5¢ per 100 searches	100% of 9 calls
Issues on one GitHub repository that use the term	`{"venue":"github","repo":"rentrival/ledger"}`	About 1.5¢ per 100 searches	100% of 82 calls

Inputs

Name	Type	Default	Meaning
`keyword`	`string`	Required	A phrase or a saved Keyword id. Your brand name as the keyword, with your domain in `exclude`, finds mentions.
`venue`	`'google-search' \| 'bing' \| 'google-maps' \| 'google-news' \| 'reddit' \| 'x' \| 'linkedin' \| 'hacker-news' \| 'youtube' \| 'tiktok' \| 'stack-overflow' \| 'github'`	`'google-search'`	Where to search, which also picks the output shape. Each site is its own job with its own price.
`repo`	`string`	None.	With `github`: the repository whose issues to read, as `owner/name`. Without it, a GitHub search is refused with `input-missing`.
`locale`	`string`	`your home Market`	The market and language, such as `en-US`.
`place`	`string`	None.	With `google-maps`: the place to search around, such as `Tacoma, WA`. Without it, a maps search is refused with `input-missing`.
`depth`	`number`	`10`	Results to read, at most 100. One price covers any depth.
`within`	`string`	`'30d'`	Posts and news only: how far back to look.
`track`	`Hostname[]`	`your Domains`	Report these hosts’ positions in `tracked`.
`exclude`	`Hostname[]`	None.	Drop results on these hosts: pass your own to find mentions you did not write.
`maxAge`	`string`	`'1d'`	A stored reading younger than this returns at $0 instead of reading again.
`maxCost`	`number`	`0.05`	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	What `null` means
`keyword`	`string`	Never null.
`results`	`Result[]`	Never null: empty when the site showed nothing, at $0.
`results[].position`	`number`	Never null: as the site shows it, ads and blocks counted.
`results[].url`	`string`	Never null.
`results[].title`	`string`	Never null.
`results[].snippet`	`string \| null`	The site shows no snippet.
`results[].host`	`Hostname`	Never null.
`results[].kind`	`'organic' \| 'ad' \| 'local' \| 'news' \| 'video' \| 'post' \| 'comment' \| 'question' \| 'issue'`	Never null: which kinds come back depends on `venue` (Output shapes).
`results[].author`	`{ handle: string; url: string \| null } \| null`	Absent on web results; `null` on a deleted account.
`results[].publishedAt`	`string \| null`, in ISO 8601	The site shows no date.
`results[].engagement`	`{ score?: number; comments?: number; views?: number } \| null`	Absent on web results.
`blocks.aiOverview`	`{ text: string; cited: { url: string; host: Hostname }[] } \| null`	The results page shows no AI answer above the results for this term today.
`blocks.peopleAlsoAsk`	`string[]`	Never null: empty when the page shows none.
`blocks.localPack`	`Result[]`	Never null: empty when the page shows no map pack.
`tracked`	`{ host: Hostname; position: number \| null; url: string \| null }[]`	Never null. `position: null` means not in the `depth` read, never position zero.
`(page)`	`Observed`	The page carries `observedAt`, `method`, `venue` and `locale`.
`cost`	`Cost`, in USD	Never null. In try mode `usd` is 0 and `maxUsd` is what the call would have cost.

Output shapes

venue picks the shape, and venue says which one came back, so your code switches on it.

A results page

When venue is google-search, bing. Ranked web results, the blocks above them, and where your hosts sit.

Field	Type	What `null` means
`results[].kind`	`'organic' \| 'ad' \| 'video' \| 'news'`	Never null.
`blocks.aiOverview`	`{ text: string; cited: { url: string; host: Hostname }[] } \| null`	No AI answer above the results for this term today. Bing returns `null` here every time.
`blocks.peopleAlsoAsk`	`string[]`	Never null: empty when the page shows none.
`tracked[].position`	`number \| null`	Not in the `depth` read, never position zero.

Local results around a place

When venue is google-maps. The map pack for place: each business, its rating and its distance order. place is required.

Field	Type	What `null` means
`results[].kind`	`'local'`	Never null.
`blocks.localPack`	`Result[]`	Never null: the same rows as `results`, in map order.
`blocks.aiOverview`	`null`	Always null on a maps search.

News results

When venue is google-news. Articles that name the term, newest first within within.

Field	Type	What `null` means
`results[].kind`	`'news'`	Never null.
`results[].publishedAt`	`string \| null`	The outlet shows no date.

When venue is reddit, x, linkedin, hacker-news, youtube, tiktok, stack-overflow, github. Posts and comments that use the term, with who wrote them and how far they spread. There is no results page, so blocks is empty and tracked lists any post on your own hosts.

Field	Type	What `null` means
`results[].kind`	`'post' \| 'comment' \| 'video' \| 'question' \| 'issue'`	Never null: `video` on YouTube and TikTok, `question` on Stack Overflow, `issue` on GitHub.
`results[].author`	`{ handle: string; url: string \| null } \| null`	`null` when the account was deleted.
`results[].publishedAt`	`string \| null`	The site shows no date.
`results[].engagement`	`{ score?: number; comments?: number; views?: number }`	Each count is absent where the site does not show it: X shows no score, Hacker News no views.

One row of each shape, as JSON

Loading the samples.

Read the result

Field	Value	What it means	What to do
`tracked.position`	8 to 30 at week 6	The page is indexed and in range, but trusted less than the pages above it.	Rewrite it from the query’s wording, and link it from your 3 strongest pages. (the week-6 rule in the search playbook)
`tracked.position`	`null` with impressions after week 6	The page is shown for the term but never reaches the top 100: it targets the wrong term.	Re-pick a term at or under your difficulty ceiling. (the week-6 rule in the search playbook)
`blocks.aiOverview`	Present	Position-one click rates on such terms fell 58% to 61% in two studies.	Answer the question in your first 50 words; the cited pages are the ones to beat. (two click-rate studies of terms with an AI answer above the results)
`results[].host`	3 or more of the top 10 hold your referring domains or fewer	The term is winnable with the links you can reach in 8 weeks.	Read each one’s referring domains with `Domain.benchmark`, then approve the term. (the winnability rule in the search playbook)
`results[].kind`	`post` with 10 or more comments this month	Buyers are asking about the problem right now, in public.	Answer the thread with a sourced reply, not a pitch. (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-Key with the same input replays the first answer at $0; with other input it returns 409.

Saved or shared

Nothing is written to your records. A results page is shared across startups for the same term, site and locale for a day; tracked is yours.

Emits

Keyword.searched with { keyword, venue, results, blocks, tracked }

Performed by

Analyst

Price

About 3¢ per 100 searches. Free: a page read younger than maxAge. maxCost defaults to 5¢. 30 results pages for a first keyword map: 30 × 0.03¢ a search is about 0.9¢.

Reliability

The first route succeeds 99.1% of 1,710,120 calls. If it fails, a second route answers at 99.9% of 148,816 calls, and you pay for one.

Freshness

A reading younger than 1 day returns at $0. Readings are shared across startups for the same subject and locale.

Batch and pages

Up to 1 term a call, up to 100 results deep. 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

Check	Error	Fix	Then call
A search engine, answer engine or network the call does not read, such as ChatGPT sent to `Keyword.measure`	`venue-unsupported`	Pick one the call’s `venue` input lists; AI answers are `Keyword.ask`, posts are `Keyword.search`.	`Keyword.ask`

Every data call can also meet the shared data-call refusals: filter-unsupported, input-missing, limit-exceeded, max-cost, rate-limited, sources-busy.

The venue-unsupported payload

JSON

{
  "type": "https://startupbuilder.dev/errors/venue-unsupported",
  "title": "The call does not read that search engine or network",
  "status": 422,
  "detail": "A search engine, answer engine or network the call does not read, such as ChatGPT sent to `Keyword.measure`.",
  "fix": "Pick one the call’s `venue` input lists; AI answers are `Keyword.ask`, posts are `Keyword.search`.",
  "next": {
    "verb": "Keyword.ask",
    "input": {
      "keyword": "best rent tracking software for a 40-unit property manager",
      "venues": [
        "chatgpt"
      ]
    }
  },
  "instance": "https://api.sb/leaseline.app/actions/action_1"
}

When it waits

Returns in one response; nothing waits.

Example

Text

Who shows up on Google for “rent tracking app for landlords”, and where
is leaseline.app? 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, and watching it

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: 0.0001`	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.

Watch it on a schedule: a Monitor runs this call and records an Event only when the reading changes.

TypeScript

await $.Monitor.create({
  verb: 'Keyword.search',
  input: { keyword: 'rent tracking app for landlords' },
  change: 'rank-change',
  threshold: 3,
  every: '1d',
})

Used by

Workflows: Keyword opportunity map · Search readout · Pick who to sell to first · Post-engager harvest
Agent tasks: Answer page per question · Answer threads · Launch day · Monthly search content · Account brief · Message test
Services: Ranked page
Jobs: Check AI answers · Earn first links · Get indexed · Make content · Measure · Publish and post · Research demand

Options and pricesCopy Anchor Link

InputsCopy Anchor Link

OutputsCopy Anchor Link

Output shapesCopy Anchor Link

A results pageCopy Anchor Link

Local results around a placeCopy Anchor Link

News resultsCopy Anchor Link

PostsCopy Anchor Link

Read the resultCopy Anchor Link

EffectsCopy Anchor Link

Refuses whenCopy Anchor Link

When it waitsCopy Anchor Link

ExampleCopy Anchor Link

Used byCopy Anchor Link

RelatedCopy Anchor Link