Crustdata MCP Integration for AI Agents

CREDIT BALANCE (/account/credits, API version 2025-11-01). FREE. The balance is under `account.credits`, with the recurring grant (recurring_credits, recurring_credits_frequency, recurring_credits_refresh_date). Accounts with credit wallets also get a `wallets` list splitting recurring (spent first) from top-up (rolls over until expires_at) — informational only; gate spending decisions on account.credits.

CREDIT BALANCE (/account/credits, API version 2025-11-01). FREE. The balance is under `account.credits`, with the recurring grant (recurring_credits, recurring_credits_frequency, recurring_credits_refresh_date). Accounts with credit wallets also get a `wallets` list splitting recurring (spent first) from top-up (rolls over until expires_at) — informational only; gate spending decisions on account.credits.

ACCOUNT ENDPOINT PERMISSIONS — NEW API (v2025-11-01). Lists every Crustdata API endpoint with this account's access status (enabled/disabled), effective rate limit in requests/minute, and — with include_fields=true — the response fields enabled and disabled for the account. FREE, no credits. THE tool for diagnosing a 403 from any v2 tool ('is this endpoint on my plan?') and for answering 'what am I allowed to call / what is my rate limit?'. Narrow with path (exact match), category, or status — filters combine with AND, and unknown path/category values return an empty list rather than an error. RESPONSE: {api_version, token_limit_rpm, endpoints: [{path, category, status, effective_rate_limit_rpm, fields?}]}.

PERSON FIELD AUTOCOMPLETE (/person/search/autocomplete, API version 2025-11-01). It replaces the retired crustdata_autocomplete_person. FREE. Resolves exact indexed values for the filters of crustdata_people_search_db_v2 and crustdata_people_search_semantic. Takes nested field paths (experience.employment_details.current.title, basic_profile.location.city, …). Suggestions come from the whole dataset — they are not narrowed by other conditions. Feed a returned value back into a search filter verbatim. For live-search values (people_search_live_v2) crustdata_autocomplete_filter_v2 is the matching tool.

COMPANY FIELD AUTOCOMPLETE (/company/search/autocomplete, API version 2025-11-01). It replaces the retired crustdata_autocomplete_company. FREE. Resolves exact indexed values for the filters of crustdata_company_search_db_v2, crustdata_company_search_semantic, and crustdata_company_search_by_technology. Takes nested field paths (locations.country, taxonomy.professional_network_industry, …); suggestions come from the whole dataset, not narrowed by other conditions. The technographics vocabulary is field='technology' (tech names, e.g. query='snow' → 'Snowflake') and field='technology_category' (kebab-case slugs, e.g. query='data' → 'data-warehouse'). Feed a returned value back into a search filter verbatim.

JOB FIELD AUTOCOMPLETE (v2025-11-01). FREE — no credits. Returns the exact indexed values a crustdata_job_search filter will accept, so use it BEFORE filtering on a free-text job field (title, category, company name, location) — a near-miss value like 'SWE' for 'Software Engineer' matches zero jobs silently. Not version-gated: crustdata_job_search already runs on the 2025-11-01 /job/search endpoint, so this is simply its value-discovery helper. Empty `query` returns the most common values for the field.

COMPANY IDENTIFY (/company/identify, API version 2025-11-01). It replaces the retired crustdata_company_identify. FREE. Resolves a company to its crustdata_company_id. Identifiers are plural arrays (up to 25 values) of exactly ONE type per call: domains / names / crustdata_company_ids / professional_network_profile_urls — for mixed identifiers, make one call per type. Crunchbase URLs are not an identify input; filter crustdata_company_search_db_v2 on social_profiles.crunchbase.url instead. RESPONSE: list of {matched_on, match_type, matches: [{confidence_score, company_data.basic_info}]}.

COMPANY ENRICHMENT (/company/enrich, API version 2025-11-01). It replaces the retired crustdata_company_enrich. Full company profile from the Crustdata dataset. Identifiers are plural arrays (up to 25 values) of exactly ONE type per call: domains / names / crustdata_company_ids / professional_network_profile_urls. The default response is basic_info only — list the sections you need in `fields` (headcount, funding, hiring, web_traffic, employee_reviews, people, news, …; see the fields parameter). 'technographics' in fields bills an add-on; for the tech stack alone crustdata_company_technographics is the purpose-built tool. Data is served from the dataset — there is no real-time refresh on this endpoint. RESPONSE: list of {matched_on, match_type, matches: [{confidence_score, company_data}]} with company_data nested by section (basic_info / headcount / funding / …).

COMPANY SEARCH — DATASET (/company/search, API version 2025-11-01). It replaces the retired crustdata_company_search_db. The primary company search: filter the Crustdata company dataset by industry, location, headcount, funding, growth, and more. Filter leaves use {field, type, value} with nested field paths (basic_info.name, headcount.total, locations.country, …); branches use {op, conditions}. Pagination is cursor-based (pass back next_cursor). Returns a markdown table by default; format='json' returns the nested records (compacted to key fields unless compact=false). Also filters on technographics (technographics.technologies.name / .category / .total_technologies), though crustdata_company_search_by_technology is the purpose-built tool for that.

COMPANY SEMANTIC SEARCH — natural-language ranked company search on the /company/search dataset (v2025-11-01). crustdata_company_search_db_v2 covers ordinary filter-based company search. This tool is for requests that describe companies by what they do — a product, capability, business model, or customer base that maps to no filter field — or that ask for semantic / natural-language search or results ranked by relevance. WHAT IT DOES: ranks companies by how well their profile (description, products, industry, specialities) matches `query`; optional `filters` are hard constraints applied before ranking; `search_mode` picks keyword, embedding, or both (hybrid, the default). KEY BEHAVIORS: (1) Results come back relevance-ordered in pages of up to 100; pass `next_cursor` back as `cursor` for more, up to 1,000 candidates per search (cursors expire after 20 minutes). `total_count` is always null and `sorts` is rejected. (2) No per-company score is returned; the order is the ranking. (3) Ranked search is enabled per account: a 'Company semantic search is not available for your account' error is that enablement, separate from /company/search access, and crustdata_company_search_db_v2 keeps working — ask Crustdata to enable it. RESPONSE: a markdown table by default; format='json' returns the same nested company records as crustdata_company_search_db_v2 (basic_info / headcount / locations / taxonomy / funding …), compacted to key fields unless compact=false.

Search the job listings database. Find jobs by company, title, location, category, and more. Supports filters, sorting, cursor pagination (up to 1000 results), and aggregations (counts/breakdowns). No charge when a query returns 0 results. Filters use 'field'/'type'/'value' keys with nested field paths (e.g., 'job_details.title', 'company.basic_info.name'). RESPONSE: By default returns a compact markdown table without descriptions. Use aggregations with limit=0 to get counts without fetching listings (e.g., 'how many engineering jobs at Google?').

PERSON ENRICHMENT (/person/enrich, API version 2025-11-01). It replaces the retired crustdata_people_enrich. Full person profile (work history, education, skills, social handles) by professional profile URL — up to 25 per call. The default response is basic_profile + social_handles only — pass `fields` for experience / education / skills / professional_network / research_profiles. COST: additive — dev-platform and research-profile field groups bill add-ons on top of the base profile (run crustdata_credit_costs for rates). Contact data (emails, phones) is not an enrich field group: crustdata_people_contact_enrich is the contact tool. OTHER IDENTIFIERS: an email (business or personal, e.g. Gmail) resolves through crustdata_batch_person_identify; a GitHub URL through crustdata_github_enrich. FRESH DATA: the cached dataset is used unless realtime=true, which fetches a fresh profile from the web (enterprise, URLs only). If the plan denies some requested fields, the cached path strips the gated fields and retries once (noted in the response). RESPONSE: list of {matched_on, match_type, matches: [{confidence_score, person_data}]}; unmatched identifiers return matches: [].

PEOPLE SEARCH — DATASET (/person/search, API version 2025-11-01). It replaces the retired crustdata_people_search_db. The primary people search: filter the Crustdata people dataset by title, employer, seniority, location, education, skills, and more. Returns vanity profile URLs (linkedin.com/in/jane-doe). crustdata_people_search_live_v2 is the real-time fallback when this returns 0 results. FILTER SHAPE: leaves use {field, type, value} (NOT 'column'). Field paths are nested, e.g. basic_profile.name, experience.employment_details.current.title, experience.employment_details.current.company_name, education.schools.school. Branches use {op: 'and'|'or', conditions: [...]}. RESPONSE: a markdown table by default (with next_cursor and remarks in the footer); format='json' returns the native nested shape — basic_profile / contact / experience / education / social_handles / professional_network, with the profile URL at social_handles.professional_network_identifier.profile_url. ZERO RESULTS: `remarks` says which condition emptied the result — a condition_eliminates_all remark carries that condition's `path` (e.g. filters.conditions[2]) and `matches_without` (how many match without it), so that condition, not the whole filter, is what needs changing. no_single_culprit means removing any one probed condition still leaves 0; its message says how many of the conditions were probed.

PEOPLE SEMANTIC SEARCH (beta) — natural-language people search on the /person/search dataset (v2025-11-01). crustdata_people_search_db_v2 covers ordinary filter-based people search. This tool is for requests that ask for semantic / natural-language search specifically — 'use semantic search', 'natural-language search', 'search by description', 'rank these by relevance', or a pasted job description with a request for similar people. WHAT IT DOES: ranks people by how well their whole profile (title, skills, company history, education, location, summary) matches `query`. KEY BEHAVIORS: (1) It always returns results — the per-profile `fit` tier (strong / possible / weak) is the quality signal; the result count is not. (2) `total_count` is the size of the ranked pool, not a count of good matches. (3) Results are already relevance-ordered — sorting is not available. PARAMS: `query` (required natural-language text); `search_mode` (hybrid/lexical/semantic); `recall_mode` (managed/exact — use 'exact' to enforce `filters` as hard constraints); `query_syntax='boolean'` reads `query` as a keyword expression (AND / | / + / - / "phrase" / prefix*; lexical + exact only); optional `filters` (same tree shape as crustdata_people_search_db_v2, leaves use 'field' not 'column'). RESPONSE: a markdown table by default (with a Fit column); format='json' returns the native nested v2 shape (basic_profile / contact / experience / education / social_handles / professional_network) plus a per-profile `fit` tier, with top-level total_count + total_count_relation (eq | gte).

RENAMED — call crustdata_batch_person_contact_enrich instead. This name is kept as a temporary alias for backward compatibility; it forwards to crustdata_batch_person_contact_enrich unchanged and will be removed in a future release. The new name says what the tool actually returns — CONTACT fields (business email / personal emails / phone numbers) — so it can't be mistaken for crustdata_batch_person_profile_enrich, which returns full profiles.

RETRIEVE AN EXISTING ASYNC BATCH by its batch_id — status plus results. Use this whenever a batch tool returned a batch_id instead of results because the job was still running: contact enrich, profile enrich, company enrich, job search, and person identify all funnel through it. It polls the job and, once complete, returns the records. It does NOT submit a new job and NEVER bills again — so when a batch times out, call THIS with the same batch_id rather than re-running the submit tool, which would start a fresh billable batch. RESPONSE: the API's job status verbatim — {batch_id, status (pending / processing / completed / failed), entity, action, identifier_count, result_count, entities_requested, entities_fulfilled, created_at, completed_at, error_message (failed jobs), download_url + download_urls (completed jobs)} — plus `results`, the downloaded records, once a completed job has any. While the job is still running, just call again later. An unknown or expired id returns a clear error (result files are retrievable for ~5 days after completion).

LIST THE ACCOUNT'S ASYNC BATCH JOBS, most recent first — every batch type (company/person enrich, contact enrich, person identify, job search). Use it to find a batch_id you no longer have, or to see what is still running. Optional `status` filter (pending / processing / completed / failed); page with `cursor` = the previous page's next_cursor while has_more is true. Summaries only, no records or download links — pass a job's batch_id to crustdata_get_batch for its results. FREE. RESPONSE: {jobs: [{batch_id, status, entity, action, identifier_count, result_count, entities_requested, entities_fulfilled, created_at, completed_at}], job_count, next_cursor, has_more}.

Retired. Company identify on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_company_identify_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Company enrichment on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_company_enrich_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Company database search on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_company_search_db_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Live company search on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_company_search_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name. crustdata_company_search_db_v2 covers it for the indexed company dataset.

Retired. Company filter autocomplete on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_autocomplete_company_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Person enrichment on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_people_enrich_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name. crustdata_people_contact_enrich covers it for emails and phone numbers.

Retired. People database search on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_people_search_db_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Live people search on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_people_search_live_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name. crustdata_people_search_db_v2 covers it for the indexed people dataset.

Retired. Person filter autocomplete on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_autocomplete_person_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Social posts by profile on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_social_posts_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name. crustdata_social_post_search covers it for the indexed post dataset.

Retired. Social post keyword search on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_social_posts_by_keyword_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name. crustdata_social_post_search covers it for the indexed post dataset.

Retired. Social post keyword search on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_social_posts_by_keyword_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name. crustdata_social_post_search covers it for the indexed post dataset.

Retired. Web search on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_web_search_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Web page fetch on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_web_fetch_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Retired. Live-search filter autocomplete on the v1 API, which has been shut down; every call returns an error and makes no API request. crustdata_autocomplete_filter_v2 covers this capability on the current API, including requests that ask for the legacy or v1 API by name.

Install Crustdata research skills locally so they appear as native /slash-commands in Claude Code (e.g., /research-person). By default writes full skill content (SKILL.md + helper files like references/, scripts/) plus a .crustdata_version marker. Each skill becomes invokable without any further server roundtrips. Use crustdata_skill_versions periodically to check whether a re-install is needed.

Return current server-side version markers for the caller's granted skills. Each version is the ISO timestamp of the most recent update to the skill in the admin DB. Compare against the .crustdata_version file written at install time — if they differ, re-run crustdata_install_skills to refresh local content. Cheap, single DB query. Safe to call once per session.

Fetch a helper file (reference, script, README, etc.) for a centrally-managed skill. Use this whenever the live SKILL.md body (from crustdata_get_skill_body) references a relative path like `references/foo.md` or `scripts/bar.py` — the file is NOT installed locally, only on the server. For executable scripts, write the returned content to a temp path before running.

Fetch the live SKILL.md body for a centrally-managed skill. The local SKILL.md installed at ~/.claude/skills/<name>/SKILL.md is intentionally a stub that points here — call this tool to get the current playbook before executing the skill. Returns the full instructions exactly as authored in the admin UI. Throws if the caller hasn't been granted access to this skill.

List the Crustdata skills your account has access to install. Use this BEFORE crustdata_install_skills to see what's available, or to confirm what was granted. Returns names + descriptions.

SOCIAL POST SEARCH (/social_post/search, API version 2025-11-01). Searches the indexed Crustdata dataset of professional-network social posts — the tool for questions about posts: what a person or company posted, posts mentioning a keyword, company, or person, the most-engaged posts on a topic, and who reacted or commented. Not X posts or tweets: crustdata_get_twitter_posts covers those. Each post carries its author (with Crustdata id, title, employer, location), engagement counts, and on request every reactor and commenter. COST: billed per post returned; limit=0 counts matches for free (run crustdata_credit_costs for rates). FRESHNESS: the index trails the live network by days to a couple of weeks; crustdata_social_posts_v2 (by author or post URL) and crustdata_social_posts_by_keyword_v2 (by keyword) fetch straight from the network when the latest posts matter. A company's posts take two calls: crustdata_company_identify_v2 (free) returns the company's crustdata_company_id — every candidate when a name is ambiguous, so the right company is picked before anything is searched — then filters actor.crustdata_entity_id = that id with actor.actor_type = 'company'. Filters use {field, type, value} leaves; a keyword is text with '[.]'. Pagination is cursor-based. RESPONSE: a markdown table by default (with total and next_cursor); format='json' returns {posts, next_cursor, total_count}.

WEB SEARCH (/web/search/live, API version 2025-11-01). It replaces the retired crustdata_web_search. Live search across web, news, academic, deep research, and social sources. Returns result titles, URLs, and snippets — not page content: to read pages, pass result URLs to crustdata_web_fetch_v2. The country param is 'location' (ISO alpha-2); 'page' aggregates that many result pages; optional human_mode for bot-protected retrieval. RESPONSE: {success, query, timestamp (ms), results[], metadata} — result shape varies by source.

WEB FETCH (/web/enrich/live, API version 2025-11-01). It replaces the retired crustdata_web_fetch. Fetch the content of 1-10 web pages. Optional human_mode (browser-like fetch for bot-protected pages). Content is the page's visible text: HTML is stripped and each page is capped at 30,000 characters (`_content_truncated` and `_content_original_chars` mark a capped page). RESPONSE is a top-level ARRAY of {success, url, timestamp (s), title, content}. Failed URLs come back as success=false with null fields, in any order — match entries by url, not index.

TECHNOGRAPHICS — what technologies a company uses (v2025-11-01). Billed as a base enrich plus a technographics add-on (rates: crustdata_credit_costs); companies with no technographics data are billed the base only. THE tool for 'what is X's tech stack?', 'does X use Snowflake?', 'what data warehouse does X run?'. Returns total_technologies (true count), top_technologies (most notable, up to 25) and — where the account has field-level permission — a detailed technologies[] list of {name, category, sources}, ordered by how central the tech is to the company. Sources are 'web signals' (the company's site) or 'job posting'. Provide EXACTLY ONE identifier list: domains, names, crustdata_company_ids, or professional_network_profile_urls. To go the other way — find companies that use a given technology — use crustdata_company_search_by_technology.

FIND COMPANIES BY TECHNOLOGY (technographics search, v2025-11-01). THE tool for 'which companies use Snowflake?', 'find companies running dbt AND Airflow', 'companies with a data warehouse', 'accounts on my competitor's stack'. Filters the company dataset on detected tech: `technologies` (names — set match='all' to require every one, default 'any'), `categories` (kebab-case slugs like 'data-warehouse'), and `min_technologies`. Narrow further with `additional_filters` (headcount.total, locations.country, …). Resolve tech names and categories first with crustdata_autocomplete_company_v2 (field='technology' or 'technology_category') — it is FREE and returns the exact stored spellings, and an unrecognised name silently matches nothing. NOTE: search FILTERS on the stack, it does not RETURN it — results are company records. To see what a matched company actually uses, pass it to crustdata_company_technographics.

Lightweight liveness probe for the Crustdata MCP server itself. Returns {status: 'ok'} when the server is reachable. Does NOT call the Crustdata API or consume credits. Use this when you need to verify the MCP connection is healthy without spending credits.

Return a markdown table of how many Crustdata credits each MCP tool call costs, broken down by variation (cached vs realtime, reactors/comments, business email, exact keyword match, per-result, etc.). Prices are the published Crustdata API prices. Free — makes no API call and consumes no credits. Answers 'how much does X cost?' and sizes spend before expensive calls. Note: credits are only charged when a call returns results.

LEGACY event watcher (v1 /watcher/watches). Every subject it covers now has a v2 watch, so create new watches with crustdata_watch_create: profile or attribute changes on known people/companies, discovery of new people/companies matching filters, new job postings (entity_type 'job'), and new professional-network social posts by keyword, person, or company (entity_type 'social_post'; not X posts or tweets). This tool covers an explicit request for a legacy /watcher/watches watch; existing legacy watches still run and are managed with the crustdata_watcher_* tools. Person press mentions are not available in either system (the v1 event type was removed); a company entity watch on the employer's news is the nearest. Note this tool fires at most once a DAY (frequency is in days); crustdata_watch_create goes hourly, so a need for fresher data is a reason to prefer it, not this. notification_endpoint is REQUIRED and must be an HTTPS URL the user controls. Ask for it rather than guessing, and never point a watch at a Crustdata-owned host. Delivered payloads are also readable in chat via crustdata_watcher_run_summary, so the user does not have to build anything against their endpoint to see results. Creating a watch is FREE; credits are only charged when the watch runs. Event types include 'job-posting-with-keyword-and-location', 'company-watch-linkedin-posts', 'linkedin-person-post-updates', and 'person-discovery-via-filters'. Use crustdata_watcher_simulate to dry-run first, crustdata_watcher_cancel to permanently stop a watch. The response includes an `api_request` field with the exact JSON body posted and a copy-pasteable curl; after creating, surface that curl to the user so they can reproduce or save it. SEE ALSO: crustdata_watch_create — the NEW v2 watch system (entity + discovery watchers on people, company, job and social post data) and the DEFAULT choice for creating any new watch.

Update an existing watcher subscription. Can change status (pause/resume), update webhook endpoint, or modify filters for certain subscription types. SEE ALSO: crustdata_watch_update — the NEW v2 watch system (entity + discovery watchers on people, company, job and social post data); prefer it for new watches. This legacy tool remains for event-webhook subscriptions.

Simulate a watcher subscription to test your webhook endpoint. Sends a test notification without creating a persistent subscription.

List the caller's watcher subscriptions, most recent first. Returns id, event_type_slug, status, frequency, created_at, last_run_id, notification_endpoint, and max_notifications_per_execution. An account with no watchers returns an empty list, which is a normal result rather than an error. By default returns the 50 most recent watchers in compact form (bulky filter payloads stripped to avoid context overflow). Use this at the start of any session that references a previously-created watch — users often forget the subscription_id, so match by event_type_slug + created_at to recover it. Pass compact=false only when the user explicitly asks to see filter details, and consider pairing with limit=10 for very active accounts. SEE ALSO: crustdata_watch_list — the NEW v2 watch system (entity + discovery watchers on people, company, job and social post data); prefer it for new watches. This legacy tool remains for event-webhook subscriptions.

Get the full details of a single watcher subscription by ID (status, filters, endpoint, frequency, etc.). SEE ALSO: crustdata_watch_get — the NEW v2 watch system (entity + discovery watchers on people, company, job and social post data); prefer it for new watches. This legacy tool remains for event-webhook subscriptions.

List recent runs of a watcher. Each entry includes the run id, status (RUNNING/SUCCESS/FAILED/SKIPPED), started_at, completed_at, new_records_count, credits_deducted, and notification_http_status. Cursor-paginated, most recent first. Use this to find out which runs have results worth inspecting (use crustdata_watcher_run_summary to fetch the actual delivered records for any run).

Fetch the detailed summary of a single watcher run: per-stage pipeline logs with timestamps AND the actual webhook payload(s) we delivered for that run. Each entry in `notifications` has sent_at, http_status, and the full `payload` we POSTed (subscription_id, event_type, timestamp, and the matching records). Use this to show the user the actual matches their watcher produced. The payloads are read back from the API and scoped to the caller's own account, so the user does not have to build a listener against their notification_endpoint to see results. If the run is still in progress, logs and notifications may be empty arrays.

Permanently cancel a watcher subscription by ID. Cancellation is irreversible — the watch stops running and cannot be reactivated (use crustdata_watcher_update with status='paused' if you only want to pause it). Notification history and run records are preserved. The cancelled watch is hidden from crustdata_watcher_list unless include_cancelled=true. SEE ALSO: crustdata_watch_cancel — the NEW v2 watch system (entity + discovery watchers on people, company, job and social post data); prefer it for new watches. This legacy tool remains for event-webhook subscriptions.

WATCH CREATE — NEW watcher system (v2025-11-01 API). Create an entity watch on people or companies, or a discovery watch on people, companies, jobs, or social posts. This is the DEFAULT tool for creating any watch; the legacy crustdata_watcher_* tools only manage watches created on the old API. Everything belongs here: profile and attribute changes on known people or companies, and discovery of new people, companies, job postings (entity_type 'job'), or professional-network social posts (entity_type 'social_post'; by keyword, author, or company) matching filters. Person press mentions are not watchable; a company entity watch on the employer's news is the nearest. Cadence is not a reason to choose v1: v1 fires at most once a DAY, this tool fires as often as hourly. mode='entity' tracks known people/companies you list for profile changes; mode='discovery' alerts on NEW records matching a saved filter. Entity mode: POST /watch/{entity_type} with entities + track (+ optional fields); billed per change notification (check crustdata_credit_costs), tiered by config.refresh_frequency_days (fresher data costs more); first run is a free baseline and no-change runs are free. Discovery mode: POST /watch/{entity_type}/search with filters (index search, the default) or, with config.is_realtime: true, realtime_filters (+ narrowing_filters) for a live search that finds records as they appear on the web, at a higher per-record rate; billed per new record delivered, first run is a free baseline of up to 5 matches. Both modes need config.trigger ({type: 'interval', every_hours: N}). Pass preview: true to validate and see what the watch would do without creating it. With no notifications channel the watch is pull-only: read its results with crustdata_watch_runs and crustdata_watch_run_summary. RESPONSE: {api_request, response} — api_request echoes the exact API call (with a copy-pasteable curl) and response is the created watch, or the preview.

WATCH LIST — NEW watcher system (v2025-11-01 API). Manages watches created by crustdata_watch_create (NOT the legacy crustdata_watcher_* watches). FREE. Lists the caller's v2 watches for one dataset (person, company, job, or social_post) as an array of watch objects (id, kind: 'entity'|'discovery', dataset, status, config, notifications, created_at, last_run_at, usage counters). Entity and discovery watches are listed by default (job and social_post have discovery watches only); pass kind to list one. Returns the first 50 by default with each watch's identifier lists collapsed to entity_count; filter with status, page with limit/offset, and use crustdata_watch_get for one watch's full payload. Never lists everything at once: an active account's full list does not fit in context.

WATCH GET — NEW watcher system (v2025-11-01 API). Manages watches created by crustdata_watch_create (NOT the legacy crustdata_watcher_* watches). FREE. Returns the full watch object (kind, dataset, status, entities/track or filters, fields, config, notifications, created_at, last_run_at). last_run_at is null until the baseline run completes.

WATCH UPDATE — NEW watcher system (v2025-11-01 API). Manages watches created by crustdata_watch_create (NOT the legacy crustdata_watcher_* watches). FREE. PATCH to pause/resume (status 'paused'/'active') and/or replace the watched entities list, config, or notifications. What a watch watches is fixed at create time (track, filters, realtime_filters, narrowing_filters, sorts, fields): create a new watch to change it. To delete permanently, use crustdata_watch_cancel. RESPONSE: {api_request, response} — api_request echoes the exact API call (with a copy-pasteable curl) and response is the updated watch.

WATCH CANCEL — NEW watcher system (v2025-11-01 API). Manages watches created by crustdata_watch_create (NOT the legacy crustdata_watcher_* watches). FREE. DELETE the watch — returns 204 No Content (surfaced here as {success: true}). Deletion is terminal; the watch cannot be resumed. If the user may want it back, pause it via crustdata_watch_update instead. RESPONSE: {api_request, response} — api_request echoes the exact API call (with a copy-pasteable curl) and response is the deletion result.

WATCH RUNS — NEW watcher system (v2025-11-01 API). Run history for a watch created by crustdata_watch_create (NOT the legacy crustdata_watcher_* watches, whose runs are crustdata_watcher_runs). FREE. Returns {runs, next_cursor, total_count}, newest first; pass next_cursor back as cursor for the next page. Each run carries status, failure_reason, credits_deducted, notification_http_status, and counters: records_searched (what the run started from), records_after_filter (what was new), new_records_count (what was delivered; below records_after_filter when the cap cut the run short), records_matched (entity runs) and records_stale (discovery runs). A non-2xx notification_http_status means matches were found but the channel refused the delivery. Read one run's records with crustdata_watch_run_summary.

WATCH RUN SUMMARY — NEW watcher system (v2025-11-01 API). One run of a watch created by crustdata_watch_create (NOT the legacy crustdata_watcher_* watches, whose summaries are crustdata_watcher_run_summary). FREE. Returns the run's status, counters, credits_deducted, logs, payload_delivery (for a 'link' watch: the pre-signed NDJSON url, format, bytes, expires_at), and notifications: every delivery attempt with sent_at, http_status, and the records it carried (payload.notifications[], each with uid and record; an entity record adds changes). This is how a pull-only watch (no channels) is read, and how to see what a webhook received. notifications is empty unless the run's status is SUCCESS. Records are capped by max_records (default 25); the remainder is counted in records_omitted. Get run ids from crustdata_watch_runs.

Find recent Twitter/X posts from a company or person by their Twitter handle. This is the Twitter/X post tool — it covers tweets, X posts and Twitter posts, which the social_posts tools do not (those cover professional-network social posts). Runs a web search on x.com (/web/search/live) and returns post titles, URLs, and snippets.