Prospect.count · SalesBuilder

GET https://api.sb/{your-domain}/prospects/count

Inputs

Name	Type	Meaning
`icp`	`string`	An ICP id; its Persona fills `where`. Pass this or `where`.
`where`	`ProspectFilter`	Titles, seniority, departments, locations, countries, the companies they work at, and `organizationWhere` for the company filters.
`kind`	`'person' \| 'creator'`	Count creators by audience instead of people by role. Default `'person'`.
`strict`	`boolean`	Refuse with `filter-unsupported`, at $0, instead of listing an unapplied filter in `ignored`. Default `false`.

Outputs

Field	Type	Unit	What `null` means
`count`	`number`	people	Never null: 0 means no one matched.
`withEmail`	`number \| null`	people	The source does not say how many have a work email on file.
`ignored`	`string[]`	None.	Never null: empty when every filter you sent was applied.
`observedAt`	`string`	ISO 8601	Never null.
`method`	`Observed['method']`	None.	Never null; counts read `'estimated'`.

Read the result

Field	Value	What it means	What to do
`withEmail`	Under half of `count`	Many of these people will cost a find that misses, which is free, before one that hits.	Plan reach from `withEmail`, not `count`. (the free-miss rule)
`count`	Under 900	At 400 new contacts a month the audience lasts about 2 months.	Widen the titles with `similarTitles`, or add a second role at the same companies. (list saturation math, our planning number)
`ignored`	`departments` listed	Department is the people filter routes take least often, about 1 call in 5, so the count is wider than asked.	Put the department words into `titles`, which routes apply on 99% of calls. (filter coverage, measured across 9,229,085 people-search calls)

Effects

Action class

None: it reads, so no approval rule names it

Modes

try: Counts and stores nothing; a count is free in every mode.
send: Returns a pending Action at once; its Event carries the rows when the read finishes.
do: Waits for the count; a count is free in every mode.

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. A count names no one, so it is shared across startups for the same filters for 7 days.

Emits

Prospect.counted with { count, withEmail, where }

Performed by

Prospector

Price

Free. Free: every count, in every mode.

Reliability

The first route succeeds 100% of 2,861,763 calls. If it fails, a second route answers at 99.1% of 30,491 calls, and you pay for one.

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 1 filter set 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

Check	Error	Fix	Then call
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, venue-unsupported.

The filter-unsupported payload

JSON

{
  "type": "https://startupbuilder.dev/errors/filter-unsupported",
  "title": "No route can apply a filter you sent",
  "status": 422,
  "detail": "A call sent with `strict: true` and a filter no route can apply.",
  "fix": "Drop that filter, or send without `strict` and read what comes back in `ignored`.",
  "next": {
    "verb": "Organization.count",
    "input": {
      "where": {
        "industries": [
          "property management"
        ],
        "headcount": {
          "min": 20,
          "max": 200
        },
        "countries": [
          "US"
        ]
      }
    }
  },
  "instance": "https://api.sb/leaseline.app/actions/action_1"
}

When it waits

Returns in one response; nothing waits.

Example

Text

How many property managers and owners work at US property management
companies with 20 to 200 staff? Spend nothing.

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

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