Create a new CatchAll processing job from a natural-language query.

Use when:

• You want to start a new CatchAll web research run from a user query.

• You want the API to fetch/process sources and then return structured results.

Do not use when:

• You want status for an existing job (use get_job_status).

• You want records for an existing job (use pull_results).

Key rules:

• query is required.

• You can submit with only query; omitted optional fields (validators, enrichments, start_date, end_date) are auto-selected/generated by the API.

• Optional fields are independent: you can pass any subset (for example, custom validators but no enrichments), and omitted fields are still auto-selected/generated.

• When connected_dataset_ids is set, the query must describe the topic or event type only (e.g. "M&A activity", "regulatory filings", "executive changes"). Do NOT write things like "for my companies", "for the selected list of companies", or "news about my watchlist" — the entity filtering is applied automatically by the connected dataset. Mentioning companies in the query when a dataset is attached is redundant and degrades retrieval quality.

• When connected_dataset_ids is set, entity-relevance validators (e.g. company_is_primary_subject) are generated automatically by the API. Do NOT add them manually to validators — they are redundant and may conflict with the auto-generated ones. Only pass validators that describe the event or topic, not entity filtering.

• start_date and end_date filter by web page discovery date, not event date.

• Discovery dates and extracted event dates can differ. For event-time accuracy, use event-focused validators/enrichments and verify event_date in pulled results.

• end_date must be after start_date.

• Dates outside your plan lookback limits return API 400.

• limit controls processed record count (cost-affecting). Omit it to retrieve everything up to your plan's maximum. If provided, must be >= 10.

• validators / enrichments may be passed either as arrays or as JSON-string arrays (for client compatibility).

• validators[].type must be boolean (if omitted, it defaults to boolean).

• enrichments[].type supported values: text, number, date, option, url, company.

Basic examples:

• validators: [{"name":"is_acquisition_event","description":"true if page describes an acquisition","type":"boolean"}]

• enrichments: [{"name":"acquiring_company","description":"Extract acquiring company","type":"company"},{"name":"deal_value","description":"Extract announced deal value","type":"number"}]

Next step:

• Save the returned job_id.

• Poll get_job_status and call pull_results (partial results can appear before completion).

Preview suggested validators, enrichments, and date ranges before submitting.

Use when:

• You want to inspect/edit auto-generated validators/enrichments before submitting.

• You want to preview date adjustments via date_modification_message.

Do not use when:

• You want to start processing immediately with final inputs (use submit_query).

Key behavior:

• Preview-only endpoint: does not create a job and does not start processing.

• Suggestions are LLM-generated and not deterministic across calls.

• To reuse suggestions, pass them explicitly to submit_query.

Check the status of a submitted job.

Call this after submit_query to see if your job is ready. Status progression: submitted -> analyzing -> fetching -> clustering -> enriching -> completed/failed

IMPORTANT: Jobs take several minutes to process. First check after ~1-2 minutes, then poll every 30-60 seconds. Broad searches can take 10-30+ minutes; for long jobs, poll every 60-120 seconds. Do NOT call this tool in a tight loop. Stop polling when status is completed or failed. Treat submitted, analyzing, fetching, clustering, and enriching as active states and continue polling.

You don't need to wait for completion to pull results. Partial results are available during enriching — call pull_results after ~2 minutes, then poll status every 30-60 seconds and pull again for fresher results. Do not stop pulling just because an intermediate pull is empty/unchanged. Use progress_validated vs candidate_records to track whether more results may still appear (progress_validated < candidate_records). If transport/session fails, resume using the same job_id.

Retrieve the results of a job.

Can be called before completion for partial results, or after completion for the full set. Returns clustered, validated, and enriched web results. While job status is active, call this repeatedly (typically page=1) to refresh partial output. When job reaches completed, iterate all pages. If job fails, call once more to capture any partial output.

Download a job's results as a CSV file.

Use when:

• You want the full job output as a CSV for offline analysis or export.

• Prefer this over pull_results when the consumer needs spreadsheet/CSV format.

Expand a job by processing more records beyond the initial limit.

This increases the number of records the system processes (which costs additional credits). Only use this when the user wants MORE data processed.

This only applies to jobs originally submitted with limit. If a job was submitted without limit, there is nothing to continue. The new_limit must be greater than the previous limit when provided. If omitted, API defaults to your plan maximum.

List all jobs submitted by you.

Returns your job history with IDs, queries, statuses, and timestamps.

Permanently delete a job and its results.

Use when:

• You want to remove a job you no longer need from your account.

Check the quality of a query before submitting a job ("Check Query Quality").

Use when:

• You want quick feedback on whether a query is well-formed for CatchAll before spending credits on a job.

• You want concrete suggestions to improve a vague or overly broad query.

Do not use when:

• You want to preview auto-generated validators/enrichments (use initialize_query).

• You want to actually run a search (use submit_query).

Create a recurring monitor from a completed job.

Monitors re-run a job's query on a schedule. Use the explore -> refine -> automate pattern: submit a job, refine until results match, then create a monitor.

The schedule is defined in natural language (e.g., 'every day at 9 AM EST'). Always include a timezone (in the schedule text or via the timezone arg). API-enforced constraints apply:

• If backfill=true, reference job end_date must be within the last 7 days

• If backfill=false, reference job age does not matter

• Minimum schedule frequency depends on your plan

Webhooks are now centralized: register them with create_webhook, then pass their IDs here via webhook_ids (there is no inline webhook config anymore).

List all your monitors.

Returns all monitors with their schedule, status, reference query, and webhook config.

Retrieve the latest results from a monitor.

Returns the most recent run's results including run_info, records, and all_records.

Download the latest monitor run's results as a CSV file.

Use when:

• You want the most recent monitor run output as a CSV for offline analysis or export.

• Prefer this over pull_monitor_results when the consumer needs spreadsheet/CSV format.

List all jobs spawned by a monitor.

Returns the history of scheduled runs for a monitor.

Disable a monitor to stop its scheduled runs.

The monitor can be re-enabled later with enable_monitor.

Enable a previously disabled monitor to resume its scheduled runs.

Update a monitor's webhook assignments and per-run limit.

Note: schedule and reference_job_id cannot be modified through this endpoint. Webhooks are centralized — pass webhook IDs (from create_webhook/list_webhooks).

Permanently delete a monitor and stop its scheduled runs.

Use when:

• You want to remove a monitor entirely (use disable_monitor to only pause it).

Get the status history of a monitor.

Use when:

• You want to see the timeline of a monitor's state changes (e.g. active, disabled, errored) and any related details.

List all your webhooks.

Use when:

• You want to see all webhook endpoints configured in your account.

• You need to find a webhook_id to pass to monitors (via webhook_ids) or jobs.

Create a new webhook endpoint.

Use when:

• You want to register a URL to receive job or monitor result deliveries.

• You need a webhook_id to attach to a monitor (via webhook_ids) or a job submission.

Retrieve the full configuration of a specific webhook.

Use when:

• You want to inspect a webhook's URL, method, headers, or status by its ID.

Update an existing webhook's configuration.

Use when:

• You want to change a webhook's URL, method, headers, or other settings.

• You want to enable or disable a webhook (set is_active).

• Only the fields you provide are updated; omitted fields remain unchanged.

Permanently delete a webhook endpoint.

Use when:

• You want to remove a webhook from your account.

Send a test delivery to a webhook endpoint.

Use when:

• You want to verify a webhook URL is reachable and correctly configured before attaching it to a monitor or job.

Map a resource (job, monitor, or monitor_group) to a webhook.

Use when:

• You want a webhook to fire for a specific job or monitor's deliveries.

List the resources mapped to a webhook.

Use when:

• You want to see which jobs/monitors a webhook is attached to.

Unmap a resource from a webhook.

Use when:

• You want to stop a webhook from firing for a specific job or monitor.

List the webhooks mapped to a specific resource (job/monitor/monitor_group).

Use when:

• You have a job or monitor ID and want to know which webhooks will fire for it.

Get the webhook delivery history for a resource (job/monitor/monitor_group).

Use when:

• You want to see past webhook delivery attempts and their outcomes for a specific job or monitor.

Manually trigger webhook delivery for a resource (job/monitor/monitor_group).

Use when:

• You want to (re-)send a webhook delivery on demand instead of waiting for the automatic dispatch — e.g. to replay a missed or failed delivery.

Create a new dataset.

Datasets are collections of entities (companies/people). Connect a dataset to a job via submit_query(connected_dataset_ids=[...]) to narrow retrieval scope.

List your datasets.

Get a single dataset's details.

Update a dataset's name and/or description.

Permanently delete a dataset.

The entities the dataset referenced are not deleted; only the dataset and its entity associations are removed.

Add existing entities to a dataset.

Remove entities from a dataset (the entities themselves are not deleted).

List the entities contained in a dataset.

Get the status history of a dataset (e.g. its enrichment progress over time).

Create a new dataset by uploading a CSV file.

The CSV must have at least a name column. For meaningful entity enrichment each row should also include a domain column or a description column (or both) — a row with only a name is accepted but produces lower-quality enrichment. Additional columns are mapped to entity attributes. Max file size is plan-dependent. To add CSV rows to an existing dataset, use append_csv_to_dataset instead.

Append entities from a CSV file to an existing dataset.

Parses the CSV and appends its entities to the dataset. Each row must have a name column; include a domain or description column (or both) for meaningful enrichment. Duplicate rows (by name) are skipped. To create a new dataset from a CSV, use create_dataset_from_csv instead.

Create a single entity (a company or person).

name is required plus at least one identifying field: either description or additional_attributes.company_attributes.domain.

List your entities.

Create multiple entities in one call.

Get a single entity's details.

Update an entity's name, description, external_entity_id, and/or attributes.

Permanently delete an entity.

Create a new project.

Projects group related resources (jobs, monitors, datasets, monitor_groups) so you can organize work and filter listings by project_id.

List your projects.

Get a single project's details.

Update a project's name and/or description.

Only the fields you provide are changed.

Delete a project.

By default the project's resources (jobs, monitors, etc.) are detached but kept. Set delete_resources=true to also delete the contained resources.

Get a project's resource overview (counts grouped by resource type and status).

Add one or more resources to a project.

List the resources contained in a project.

Remove a single resource from a project.

Retrieve plan features and current usage limits for your API key.

Use when:

• You want to know how many records/jobs/monitors your plan allows.

• You want to check current usage against plan limits before running a large job.

Check API health status.

This tool maps to GET /health and does not require an API key.

Get current API version.

This tool maps to GET /version and does not require an API key.