Give your agent qualified prospects, not raw pages.

Recommended interface

Remote MCP

Point any Streamable HTTP client at https://crawdar.com/api/mcp. Start with sandbox_businesses to test your integration without consuming live search capacity.

Every tool publishes an explicit JSON output schema. Keep each jobToken private, honor progress and retry intervals, and keep evidence URLs attached.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "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
    }
  }
}

Copy and paste

Connect your client.

Claude Code or another .mcp.json client

{
  "mcpServers": {
    "crawdar": {
      "type": "http",
      "url": "https://crawdar.com/api/mcp"
    }
  }
}

Claude Code can also connect from the command line with claude mcp add --transport http crawdar https://crawdar.com/api/mcp.

Codex

Add this to ~/.codex/config.toml:

[mcp_servers.crawdar]
url = "https://crawdar.com/api/mcp"

OpenAI Responses API

import OpenAI from "openai";

const openai = new OpenAI();
const response = await openai.responses.create({
  model: "gpt-5",
  input: "Find independent veterinary clinics in Berlin. Keep the source URLs.",
  tools: [{
    type: "mcp",
    server_label: "crawdar",
    server_description: "Evidence-backed public business research",
    server_url: "https://crawdar.com/api/mcp",
    allowed_tools: ["research_businesses", "search_businesses"],
    require_approval: "never"
  }]
});

console.log(response.output_text);

Search and sandbox tools are read-only. Clients can require approval for cancel_lead_search.

Direct integration

REST API

Test without quota or provider calls

curl https://crawdar.com/api/v1/sandbox/search \
  -H 'content-type: application/json' \
  -d '{ "target": "independent veterinary clinics", "geography": "Berlin, Germany" }'

Sandbox businesses are fictional and schema-compatible. Never use them as real leads.

Get a free agent key

Sign in with ChatGPT at your account page to create a key. The secret is shown once. Verified accounts receive 25 searches per UTC day shared across all their keys, with up to two new keys per day. Revoke a key using DELETE /api/v1/keys.

# Sign in at https://crawdar.com/account and create your key there.
# Store the displayed secret, then check your shared account allowance:
curl https://crawdar.com/api/v1/account -H "x-api-key: $CRAWDAR_API_KEY"

Send the returned secret as x-api-key or Authorization: Bearer YOUR_KEY to the REST API or as a custom header in an MCP client. Guests can run three searches in total without signing in. Existing unclaimed keys have a grace allowance until October 7, 2026 at 00:00 UTC; claim them from your account page.

Two searches can run concurrently per account. Up to ten queued or running jobs can wait in the asynchronous workflow. Poll the same queued job and honor Retry-After. Included searches depend on shared free provider capacity. If it or your daily allowance is exhausted, fresh searches use prepaid credits when available. Cached results stay free and failed searches return their search credit; a completed fresh search counts even when no matches are found. Read usage and any configured capacity offer at GET /api/v1/account.

Run a search

POST a target and geography to the stable v1 endpoint. Add an Idempotency-Key when starting a resumable job so network retries cannot create duplicate work.

curl https://crawdar.com/api/v1/search \
  -H 'content-type: application/json' \
  -H "x-api-key: $CRAWDAR_API_KEY" \
  -d '{
    "target": "independent veterinary clinics",
    "geography": "Berlin, Germany",
    "qualifier": "Must show an active first-party website. Exclude directories and chains.",
    "fields": ["Website", "Location", "Business email", "Source links"]
  }'

The response includes results, searched sources, warnings, diagnostics, remaining free searches, and evidence URLs. See the OpenAPI 3.1 contract or live status.

Browser fallback

Headless browser access

A JavaScript-capable browser can use the normal product. The core controls have stable names and test IDs for Playwright, Browser Use, and similar agents.

1. Open https://crawdar.com/.
2. Fill [data-testid="target-input"] and [data-testid="quick-geography-input"].
3. Click [data-testid="quick-search-button"].
4. Wait for [data-testid="search-results"], then inspect the Qualified, Possible, and Excluded lanes.

Prefer MCP or the API when possible. They return structured JSON without UI automation.

Keep your research

Persistent prospect lists

Use your lists or /api/v1/lists with a verified account. Create a named list, then import a completed search using its signed searchToken or its jobId and private jobToken. Rename with PATCH /api/v1/lists/{id} or delete the list and its saved rows with DELETE /api/v1/lists/{id}. Businesses are deduplicated across searches. Filter prospects by text, status, or contact availability, then export CSV for CRM import with source evidence and observation dates.

POST /api/v1/lists/{id}/refresh checks one prospect with evidence older than seven days per call and reports changed fields. Previous evidence remains when no current match is found. Refresh uses normal search allowances. Accounts can keep 100 lists with 1,000 prospects each.

Recommended agent loop

Search, inspect, then act.

1. Call explain_crawdar once when result semantics are unfamiliar.
2. For a resumable workflow, call start_lead_search and store the returned id and jobToken securely.
3. Call get_lead_search with view: "compact" and a small limit. If status is running, honor the retry interval. If it is retryable, call retry_lead_search.
4. Inspect evidence and qualification checks. Keep source URLs with every downstream record.
5. If results are empty, inspect diagnostics and explained exclusions before refining the brief.
6. Pass nextCursor back unchanged. Request full only when detailed evidence is needed.

Operating rules

Keep the evidence attached.