URL: /code/data/organizations/find · Id: `page:/code/data/organizations/find`

# Organization.find

> List the companies that fit your customer, best first, each with the quote from its own site that shows why.

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

List the companies that fit your customer, best first, each with the quote from its own site that shows why.

- **Price:** 3.8¢ per 100 rows
- **Success rate:** 100% of 185,187 calls
- **Freshness:** Fresh for 30 days
- **Emits:** `Organization.found`
- **Capability:** [Enrichment](https://startupbuilder.dev/systems/sales/enrichment)

```text title="Run it · Ask"
List the US property managers that still track rent in spreadsheets, best first, with the quote that shows it; spend up to 1¢.
```

```ts title="Run it · SDK"
import { $ } from 'startup-builder'

const result = await $.try.Organization.find({ question: 'US property managers with 20 to 400 units who still track rent in spreadsheets', limit: 2, maxCost: 0.01 })
```

```json title="Run it · Response"
{
  "organizations": [
    {
      "name": "Harborview Property Management",
      "hostname": "harborview-pm.com",
      "industry": "Real estate",
      "headcount": 34,
      "country": "US",
      "region": "US-WA",
      "fit": {
        "score": 0.86,
        "verdict": "strong"
      },
      "evidence": [
        {
          "quote": "Owners receive a monthly statement exported from our rent spreadsheet.",
          "url": "https://harborview-pm.com/owners"
        }
      ],
      "observedAt": "2026-10-27T14:02:11Z",
      "method": "sampled"
    },
    {
      "name": "Crestline Residential",
      "hostname": "crestline-residential.com",
      "industry": "Real estate",
      "headcount": 61,
      "country": "US",
      "region": "US-TX",
      "fit": {
        "score": 0.52,
        "verdict": "possible"
      },
      "evidence": [
        {
          "quote": "Renewal notices go out 60 days before lease end.",
          "url": "https://crestline-residential.com/residents"
        }
      ],
      "observedAt": "2026-10-27T14:02:11Z",
      "method": "sampled"
    }
  ],
  "after": "org_9Qe2",
  "total": 4180,
  "ignored": [],
  "cost": {
    "usd": 0,
    "maxUsd": 0.004,
    "units": 2,
    "misses": 0
  }
}
```

## Options and prices
| You get | Input that selects it | Price | Success rate |
| --- | --- | --- | --- |
| Companies that fit your filters | `{"where":{}}` | About 3.8¢ per 100 rows | 100% of 185,187 calls |
| Companies that fit a sentence | `{"question":"…"}` | About 20¢ per 100 rows | 99.99% of 38,696 calls |
| Companies like ones you already have | `{"similarTo":["harborview-pm.com"]}` | About 0.04¢ a row | 100% of 738 calls |
| Companies that run a product | `{"where":{"technologies":["…"]}}` | About $1.00 per 100 rows | 100% of 3,320 calls |
| Companies that raised this month | `{"where":{"event":{"kind":"funded"}}}` | About 4¢ a row | 98.8% of 345 calls |
| Companies hiring for a role | `{"where":{"hiringFor":["…"]}}` | About 5¢ per 100 rows | 99.9% of 5,524 calls |
| Local businesses near a place | `{"where":{"near":{"place":"…"},"category":"…"}}` | About 1¢ per 100 places | 99.98% of 1,840,000 calls |

## Inputs
| Name | Type | Default | Meaning |
| --- | --- | --- | --- |
| `icp` | `string` | None. | An ICP id; its saved filters fill `where`. Pass one of `icp`, `where`, `question` or `similarTo`. |
| `where` | [`OrganizationFilter`](/code/data/types#organizationfilter) | None. | The filters every Organization call takes. Selects the Companies that fit your filters job. |
| `where.event` | `{ kind: 'funded' \| 'hiring' \| 'technology-added' \| 'news'; within: string; rounds?: string[] }` | `within: '30d'` | Only companies with this dated fact in the window. With `funded`, list `rounds`, or debt rounds fill the list. |
| `where.near` | `{ place: string; radiusKm: number }` | `radiusKm: 25` | Local businesses around a place; pair it with `where.category`. |
| `question` | `string` | None. | Your customer in one sentence. Each row gains `fit` and `evidence`, read from the company’s own site. |
| `similarTo` | [`Hostname[]`](/code/data/types#hostname) | None. | Up to 10 companies you already like; the rows are their lookalikes, best first. |
| `limit` | `number` | `25` | Rows a page, at most 100. You pay for rows returned, never rows asked for. |
| `after` | [`Cursor`](/code/data/types#cursor) | None. | The cursor from the last page. |
| `save` | `number` | `0` | Save the first n rows as Prospects. Saving is a write, so it follows the call’s Mode; it is free. |
| `maxCost` | `number` | `1.00` | The most this call may spend, in USD. Over it, the call is refused before it spends, or stops early with what it has. |
| `strict` | `boolean` | `false` | Refuse with `filter-unsupported`, at $0, instead of listing an unapplied filter in `ignored`. |

## Outputs
| Field | Type | What `null` means |
| --- | --- | --- |
| `organizations` | `Organization[]` | Never null: empty when nothing matched, at $0. |
| `organizations[].hostname` | [`Hostname`](/code/data/types#hostname) | Never null: a company is keyed by its domain. |
| `organizations[].name` | `string` | Never null. |
| `organizations[].industry` | `string \| null` | Unknown: no source classifies it. |
| `organizations[].headcount` | `number \| null`, in people | Unknown, never zero. |
| `organizations[].country` | `string \| null`, in ISO 3166-1 | Unknown. |
| `organizations[].region` | `string \| null`, in ISO 3166-2 | Unknown. |
| `organizations[].fit` | `{ score: number; verdict: 'strong' \| 'possible' \| 'no' \| 'unknown' }`, in score 0 to 1 | Absent without `question`. `unknown` means no quote on the site could be confirmed word for word. |
| `organizations[].evidence` | `{ quote: string; url: string }[]` | Absent without `question`. Every quote appears verbatim on the page it cites. |
| `organizations[].similarity` | `{ score: number; reason: string }` | Absent without `similarTo`. |
| `organizations[].event` | `{ kind: string; date: string; summary: string; url: string }` | Absent without `where.event`. |
| `organizations[].place` | `{ address: string; phone: string \| null; rating: number \| null; reviews: number \| null }` | Absent without `where.near`. |
| `organizations[]` | [`Observed`](/code/data/types#observed) | Each row also carries `observedAt` and `method`, and `venue` and `locale` where the reading has them. |
| `after` | [`Cursor`](/code/data/types#cursor) | The last page: there are no more rows. |
| `total` | `number \| null`, in companies | The source does not report a total. |
| `ignored` | `string[]` | Never null: empty when every filter you sent was applied. |
| `cost` | [`Cost`](/code/data/types#cost), in 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 |
| --- | --- | --- | --- |
| `fit.verdict` | `strong` on fewer than 15 of the first 25 rows | The sentence does not separate your customer from the rest of the industry. | Rewrite the sentence from the words your best calls used before you buy more rows. (a 60% fit floor, our planning number) |
| `fit.verdict` | `unknown` | No quote on the company’s own pages could be confirmed word for word. | Keep it out of a first batch; it costs the same as a strong row. (the checked-quote rule) |
| `evidence` | A quote dated in the last 30 days | You have a public reason to write now. | Quote it in the first email; trigger lists are planned to reply at twice the rate. (our planning number, measured by a 50/50 split in month 1) |
| `ignored` | `fundingStages` listed | Funding stage is the filter routes take least often: fewer than 1 call in 100 reaches a route that applies it. | Ask for `where.event` with `kind: funded` and `rounds` instead; that read applies it on every call. (filter coverage, measured across 463,483 company-search calls) |
| `event.kind` | `funded`, on a loan or a credit line | Without `rounds`, debt rounds fill a funded list. | Pass `rounds: ['seed', 'series-a']`. (reviews of the funding read) |

## 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**

Rows are returned, not saved, unless you pass `save`. Company rows are shared across startups for 30 days; `fit` and `evidence` are yours.

**Emits**

`Organization.found` with `{ organizations, where, question, total }`

**Performed by**

[Prospector](https://startupbuilder.dev/agents/sales/prospector)

**Price**

About 3.8¢ per 100 rows. Free: saving rows as Prospects, pages with no rows. `maxCost` defaults to $1.00. 100 companies that fit a sentence, each with its quote: 100 × 0.2¢ a row is about 20¢.

**Reliability**

The first route succeeds 100% of 185,187 calls. If it fails, the call refuses with `sources-busy` and 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 rows a page. Pages with an `after` cursor, 25 rows a page by default and 100 at most. A `question` call over 50 rows reads each site, so it answers in `send` mode with a pending Action at once

**Rate**

[The shared rate rules](/code/data#rate): 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`](/code/refusals#filter-unsupported) | Drop that filter, or send without `strict` and read what comes back in `ignored`. | [`Organization.count`](/code/data/organizations/count) |

Every data call can also meet [the shared data-call refusals](/code/refusals#data-calls): [`input-missing`](/code/refusals#input-missing), [`limit-exceeded`](/code/refusals#limit-exceeded), [`max-cost`](/code/refusals#max-cost), [`rate-limited`](/code/refusals#rate-limited), [`sources-busy`](/code/refusals#sources-busy), [`venue-unsupported`](/code/refusals#venue-unsupported).

```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

**Ask**

```text
List the US property managers that still track rent in spreadsheets,
best first, with the quote that shows it; spend up to 1¢.
```

**API**

```bash
curl -X POST "https://api.sb/leaseline.app/organizations/find?mode=try" \
  -H "Authorization: Bearer $SB_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"question":"US property managers with 20 to 400 units who still track rent in spreadsheets","limit":2,"maxCost":0.01}'
```

The response is the one in the Run it window above.

**CLI**

```bash
npx startup-builder do Organization.find --try --data '{"question":"US property managers with 20 to 400 units who still track rent in spreadsheets","limit":2,"maxCost":0.01}'
```

**MCP**

```json
{
  "name": "do",
  "arguments": {
    "mode": "try",
    "code": "return await $.Organization.find({ question: 'US property managers with 20 to 400 units who still track rent in spreadsheets', limit: 2, maxCost: 0.01 })"
  }
}
```

**SDK**

```ts
import { $ } from 'startup-builder'

const result = await $.try.Organization.find({
  question: 'US property managers with 20 to 400 units who still track rent in spreadsheets',
  limit: 2,
  maxCost: 0.01,
})
```

To retry, send the same `Idempotency-Key`: the retry returns the first answer for $0. A new key reads again.

A `sk_test_` key answers these the same way every time, at $0 ([every test value](/code/data#test-values)).

| Test value | Always returns | What it is for |
| --- | --- | --- |
| `maxCost: 0.0001` | Refuses with [`max-cost`](/code/refusals#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`](/code/refusals#rate-limited) | Any call naming this hostname answers 429 with Retry-After, so your retry logic runs. |
| `sources-busy.test` | Refuses with [`sources-busy`](/code/refusals#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.

```ts
await $.Monitor.create({
  verb: 'Organization.find',
  input: { where: { industries: ['property management'], event: { kind: 'funded', within: '7d' } } },
  change: 'funding',
  every: '1w',
})
```

## Used by
- **Workflows:** [Champion moved](/capabilities/keep-and-grow/champion-moved) · [Build a verified list](/capabilities/find-customers/build-a-verified-list) · [Buying-trigger feed](/capabilities/find-customers/buying-trigger-feed) · [Lookalikes](/capabilities/find-customers/lookalikes) · [Pick who to sell to first](/capabilities/find-customers/pick-who-to-sell-to)
- **Jobs:** [Find your first customers](/capabilities/find-customers)

## Related
[`Organization.count`](/code/data/organizations/count) · [`Organization.enrich`](/code/data/organizations/enrich) · [`Organization.resolve`](/code/data/organizations/resolve)