# Crawdar

> Crawdar helps builders find customer problems in business reviews. Try the Pain Point Finder first, with five free scans and no signup. The Lead List Builder is a second tool for researching companies against an ideal-customer brief.

## Customer pain point discovery

- [Customer Pain Point Finder](https://crawdar.com/): Find recurring customer complaints in sampled business reviews. Start with optional problem categories, industry, location, or custom comma-separated literal phrases. Select multiple problem categories; adjust recency and minimum distinct reviewers. Up to three businesses per scan.
- [Free beta signup](https://crawdar.com/beta): Enter an email and agree to beta feedback contact to remove the daily review-scan cap while beta is open. Provider capacity limits apply.
- Review sources can be unavailable. Security complaints are reported concerns, not verified vulnerabilities. Findings do not prove willingness to pay or guarantee customers.

## Agent interfaces

- [Agent guide](https://crawdar.com/agents): MCP, API, and headless-browser instructions.
- [MCP Streamable HTTP](https://crawdar.com/api/mcp): Remote MCP endpoint with one-call research plus durable start, get, refine, and export-aware workflows.
- [Official MCP Registry](https://registry.modelcontextprotocol.io/?q=com.crawdar%2Fbusiness-research): Published as com.crawdar/business-research.
- [OpenAPI 3.1](https://crawdar.com/openapi.json): Machine-readable REST contract.
- [REST search](https://crawdar.com/api/v1/search): JSON POST endpoint.
- [Agent skill](https://crawdar.com/skills/crawdar-business-research/SKILL.md): Portable instructions for skill-aware agents.
- [Lead List Builder](https://crawdar.com/business-list-builder): JavaScript-capable company research workflow.

Lead discovery includes three guest searches in total. For continued use, sign in with ChatGPT at https://crawdar.com/account and create an API key there. Verified accounts receive 25 searches per UTC day, shared across all their keys. Up to two keys can be issued per account per day. Store each secret when shown, then send it as `x-api-key` or `Authorization: Bearer YOUR_KEY`. Manage an existing key at https://crawdar.com/api/v1/keys: GET reads shared usage and DELETE revokes the presented key. Existing unclaimed keys have a temporary grace allowance until October 7, 2026 at 00:00 UTC; claim yours from the signed-in account page before then.

Included searches are subject to shared free provider capacity. If that capacity or your daily allowance is exhausted, fresh searches use prepaid credits when available. Cached searches stay free; failed searches return their search credit. Provider capacity already used by a failed attempt is not restored. A completed fresh search uses one search even when no matching results are found. Two searches can execute concurrently per account; the asynchronous endpoint accepts up to ten queued or running jobs. Poll the same queued job and honor `Retry-After` instead of creating duplicates. Integration sandbox results remain free and fictional. Read current usage and any available prepaid offer at `GET /api/v1/account`; prices are shown only when configured.

## Recommended MCP workflow

1. Call explain_crawdar once if result semantics are unfamiliar.
2. Test integrations without quota or provider calls at https://crawdar.com/api/v1/sandbox/search or with sandbox_businesses. Results are fictional.
3. Call research_businesses for a quick one-call result, or start_lead_search for a durable search job.
4. For resumable jobs, store the returned jobToken privately and call get_lead_search with view compact and limit 10. Honor retryAfter, or call retry_lead_search when retryable is true.
5. Add an Idempotency-Key when creating resumable jobs. Use cancel_lead_search when queued or running work is no longer needed.
6. Keep source URLs attached to every downstream record and inspect diagnostics before treating zero results as exhaustive.
7. Pass nextCursor back unchanged. Use refine_lead_search to create a new job without changing the original.
8. Check live service and quality-canary state at https://crawdar.com/api/status.

The durable job response includes an exportUrl. Request it with Authorization: Bearer JOB_TOKEN. CSV is the default; add ?format=json for JSON.

Example research_businesses arguments:

{"brief":"Independent veterinary clinics in Berlin with an active first-party website. Exclude directories and chains.","output":"compact","limit":10,"offset":0}

## Persistent prospect lists

Sign in at https://crawdar.com/lists or use an account API key. `GET /api/v1/lists` lists your lists; `POST /api/v1/lists` with `{"name":"My prospects"}` creates one. `GET /api/v1/lists/{id}` returns rows and supports `q`, `status`, and `contact` filters. Import an existing search using `POST /api/v1/lists/{id}` with either `{"searchToken":"SIGNED_SEARCH_TOKEN"}` or `{"jobId":"COMPLETED_JOB_ID","jobToken":"PRIVATE_JOB_TOKEN"}`. Duplicate businesses are merged across searches; keep tokens private. Rename with `PATCH /api/v1/lists/{id}` and `{"name":"New name"}`; `DELETE /api/v1/lists/{id}` deletes the list and its saved rows. Accounts can retain 100 lists and 1,000 prospects per list.

`POST /api/v1/lists/{id}/refresh` checks one due prospect at a time, returning changed fields when a current match is found. Evidence older than seven days is eligible; missing matches preserve previous evidence and its original observation date. Refresh uses normal search allowances. `GET /api/v1/lists/{id}/export` downloads filtered CSV suitable for CRM import, including evidence and observation dates. This is CSV export, not an automatic CRM connection.

## Minimal REST request

POST https://crawdar.com/api/v1/search with content-type application/json:

{"target":"independent veterinary clinics","geography":"Berlin, Germany","qualifier":"Must show an active first-party website.","fields":["Website","Location","Business email","Source links"]}

Free API and MCP usage is rate limited. A 429 response includes retry-after. Treat confidence as an evidence signal, not a guarantee. Verify evidence URLs before outreach or other action.

Results are separated into qualified and possible prospects. Qualified means the recorded qualification checks passed, not a guarantee that every nuance of a natural-language brief was understood. Inspect criteria against the original brief before acting. Possible means the entity appears to be a real business but at least one criterion remains unknown. Each accepted result includes whyMatch, criteria, and contactRoute. Compact MCP results expose sourceUrls; full REST and sandbox results retain evidence[].url. Rejected candidates include an exclusion reason so zero-result searches remain auditable.

## Product and policies

- [Business list builder](https://crawdar.com/business-list-builder): Product capabilities and evidence model.
- [Search templates](https://crawdar.com/templates): Ready-made workflows.
- [Crawler policy](https://crawdar.com/bot): Identification, robots.txt, and opt-outs.
- [Privacy](https://crawdar.com/privacy): Data processing and retention.
- [Terms](https://crawdar.com/terms): Permitted and prohibited use.

Crawdar is not designed for sensitive personal data, high-impact decisions about individuals, access-control bypasses, or unlawful marketing.

## Private opportunity workspaces

[Opportunity workspaces](https://crawdar.com/workspaces) retain a capability profile, problem theses, businesses, supporting and contradictory evidence, validation milestones, monitor configuration, and radar signals. They require a verified account or an account-linked API key and are private to that account. This is not a shared public opportunity Atlas or an independently verified demand feed.

MCP tools: `list_opportunity_workspaces`, `create_opportunity_workspace`, `get_opportunity_workspace`, `update_opportunity_workspace`, and `research_opportunity_workspace`. Create with `{"name":"Callback workflow research","profile":{"skills":["integrations"],"industries":["clinics"]}}`. Read the current `revision` before updates; submit one `command` and that revision. On 409, re-read before retrying. Use an `idempotencyKey` for create retries.

Equivalent REST routes: `GET/POST /api/v1/workspaces`, `GET/PATCH/DELETE /api/v1/workspaces/{id}`, `POST /api/v1/workspaces/{id}/research` with `{"revision":1,"target":"independent clinics","geography":"London"}`, and `GET /api/v1/workspaces/{id}/export?format=json` (or `format=markdown`). Add `opportunityId` to export a delivery-packet draft. Delete requires the current revision as a query parameter. Keep private exports and evidence links confidential.

Workspace research performs a bounded public review scan of up to three businesses, subject to provider capacity and configured limits. It retains source evidence and limitations. Public complaints are investigation signals, not owner-confirmed needs or willingness to buy. Missing review coverage is not proof that a problem is absent. Monitor settings and radar events preserve research history; inspect execution status and limitations rather than assuming continuous or exhaustive coverage.

Commercial milestones progress separately: observed, confirmed, interested, pilot_agreed, paid, delivered, measured, repeatable. Record a business and attributable evidence first. Milestones require same-business supporting evidence, an actor and occurrence date. Payment requires a positive amount/currency and an experiment-result payment reference; measurement requires a metric, baseline, result and unit. Inference and contradictory evidence cannot establish a milestone. User-supplied records are not independently audited transactions. A delivery-packet export is a draft and authorizes no contact, payment, publication, account access, or implementation.

## Shared graph, owner demand, providers, and learning
- Public graph: https://crawdar.com/api/v1/graph and https://crawdar.com/graph
- Owner demand and provider profiles: https://crawdar.com/network
- API: https://crawdar.com/api/v1/network/demands and https://crawdar.com/api/v1/network/providers
- Compare declared provider fit: https://crawdar.com/api/v1/network/matches?demandId=REQUEST_ID
- Private learning: https://crawdar.com/api/v1/learning and https://crawdar.com/learning
- Public material is explicitly published; private workspaces are never shared automatically. Graph contributions require an exact public preview and acknowledgment.
- Demand publication requires current website-control proof, which is not legal ownership verification. Provider capabilities remain self-reported. Applications and accepted in-app conversations are private and create no contract or payment.
- Milestones are participant-recorded. Public outcome summaries require confirmation and consent from both participants. Either may dispute a record or revoke public consent. Learning suppresses small cohorts and preserves negative, unchanged, and unknown results.