Handle.find · SalesBuilder

POST https://api.sb/{your-domain}/handles/find

Inputs

Name	Type	Meaning	Price
`venue`	`'instagram' \| 'tiktok' \| 'youtube' \| 'x'`	Where the accounts are. Each Venue fills the same row; On each Venue says what each one adds. Required.	Included
`venue: 'youtube'`	Option	YouTube channels that match a term	About 10¢ per 100 searches; works 100% of 7,600 calls
`topic`	`string`	The accounts in one sentence: `creators who explain rental-property finances to small landlords`. Each row says whether it matched the topic, the filters or both. Selects accounts that post about a topic, described in a sentence.	About 7¢ per 100 accounts; works 100% of 3,251 calls
`keywords`	`string[]`	Short words that must appear in the bio, in the account’s own language: `landlord`, not `property management software`.	Included
`followers`	`Range`	Followers or subscribers, such as `{ min: 10000, max: 100000 }`: big enough to matter, small enough to answer.	Included
`followers.min: 10000`	Option	Accounts by follower range, engagement and country	About 60¢ per 100 accounts; works 99.91% of 12,814 calls
`engagementRate`	`Range`	Reactions and comments a post as a share of followers, 0 to 1: `{ min: 0.02 }` drops bought audiences.	Included
`countries`	`string[]`	Where the account is, by country, as ISO 3166-1 codes such as `US`. Default `your home Market`.	Included
`limit`	`number`	Accounts a page, at most 50. You pay for accounts returned, so keep it small while you tune filters. Default `10`.	Included
`after`	`Cursor`	The cursor from the last page.	Included
`strict`	`boolean`	Refuse with `filter-unsupported`, at $0, instead of listing an unapplied filter in `ignored`. Default `false`.	Included
`maxCost`	`number`	The most this call may spend, in USD. Over it, the call is refused before it spends, or stops early with what it has. Default `0.25`.	Included

Outputs

Field	Type	What `null` means
`handles`	`FoundHandle[]`	Never null: empty when nothing matched, at $0. What it means Under 0.01 at 50,000 followers or more: Most of the audience does not see or answer the posts. Skip it for a paid spot; measure the posts first with `Handle.measure`. Planning estimate. `topic` only: The account talks about your problem but missed a hard filter, usually the follower range. Read why with `Handle.measure` before you drop it: a small account on topic often converts better than a large one off it. Planning estimate.
`handles[].handle`	`string`	Never null: `@smalllandlordmath`.
`handles[].name`	`string \| null`	The account shows no display name.
`handles[].url`	`string`	Never null.
`handles[].followers`	`number`, in followers or subscribers	Never null.
`handles[].engagementRate`	`number \| null`, in 0 to 1	Fewer than 10 recent posts to average over.
`handles[].country`	`string \| null`	The account names no country.
`handles[].bio`	`string \| null`	The account has no bio.
`handles[].match`	`'filters' \| 'topic' \| 'both'`	Never null: which read found it. `both` is the strongest row.
`handles[]`	`Observed`	Each row also carries `observedAt`, `method` and `venue`.
`after`	`Cursor`	The last page: there are no more rows.
`total`	`number \| null`, in accounts	The topic read reports no total.
`ignored`	`string[]`	Never null: a filter the Venue does not take, such as `keywords` on a described search.
`cost`	`Cost`, in USD	Never null. In try mode `usd` is 0 and `maxUsd` is what the call would have cost.

On each Venue

Venue	What comes back	Limits
Instagram	Accounts with followers, engagement rate and country; over 10,000 followers, the audience’s countries and ages too.	`country` is the country only: a city matches nothing.
TikTok	Accounts with followers and engagement rate.	Words in the bio filter; words in captions are not read, so put topic words in `keywords`.
YouTube	Channels with subscribers as `followers`, and engagement rate from recent videos.	Engagement rate is null for a channel with fewer than 10 recent videos. Price About 10¢ per 100 searches
X	Accounts with followers and engagement rate.	The weakest Venue for a niche: reviews found mostly off-topic accounts for software topics; pair it with `topic`.
LinkedIn	Nothing: no route lists LinkedIn members by audience.	Refuses with `venue-unsupported`; find the people who post on a topic with `Post.find` and take their authors.
Reddit	Nothing: Reddit accounts hold no follower audience to list.	Refuses with `venue-unsupported`; read a community with `Post.find`.
Hacker News	Nothing: Hacker News accounts hold karma, not an audience.	Refuses with `venue-unsupported`.
Facebook	Nothing: no route lists pages by audience.	Refuses with `venue-unsupported`; measure a page you already know with `Handle.measure`.

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 list is shared across startups for the same filters and Venue for 7 days; it reads public accounts only.

Emits

Handle.found with { venue, handles, total }

Performed by

Partner Manager

Price

About 60¢ per 100 accounts. Free: a page with no accounts, a refused filter. maxCost defaults to 25¢. Ten accounts on each of 3 Venues: 30 × 0.6¢ an account is about 18¢.

Reliability

The first route succeeds 99.91% of 12,814 calls. If it fails, the call refuses with sources-busy and nothing is spent.

Freshness

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

Batch and pages

Up to 50 accounts a page. Pages of 25 rows by default, 100 at most; pass after for the next page. It answers in one response.

Rate

The shared rate rules: 10 calls a second per key, and an array input counts as one call.

Capability

Market data

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`
A call sent with `strict: true` and a filter no route can apply	`filter-unsupported`	Drop that filter, or send without `strict` and read what comes back in `ignored`.	`Organization.count`

Every data call can also meet the shared data-call refusals: 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

A refusal: LinkedIn lists no members by audience, so the call refuses at $0 and next names the read that finds who posts on the topic there.

You, to your agent

Which LinkedIn creators post about property management software?

Response, in try mode

{
  "type": "https://startupbuilder.dev/errors/venue-unsupported",
  "title": "The call does not read that search engine or network",
  "status": 422,
  "detail": "Handle.find does not list LinkedIn members by audience.",
  "fix": "Find who posts on the topic with Post.find on LinkedIn, then measure each author with Handle.measure.",
  "next": {
    "verb": "Post.find",
    "input": {
      "term": "property management software",
      "venue": "linkedin"
    }
  },
  "instance": "https://api.sb/leaseline.app/actions/action_Li7wK2"
}

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

Used by

None.

InputsCopy Anchor Link

OutputsCopy Anchor Link

On each VenueCopy Anchor Link

EffectsCopy Anchor Link

Refuses whenCopy Anchor Link

When it waitsCopy Anchor Link

ExampleCopy Anchor Link

Used byCopy Anchor Link

RelatedCopy Anchor Link