submit_query
Start a web research job by submitting a natural-language query. The API fetches and processes sources, then returns structured results.
Instructions
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:
queryis 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
validatorsbut noenrichments), and omitted fields are still auto-selected/generated.When
connected_dataset_idsis set, thequerymust 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_idsis set, entity-relevance validators (e.g.company_is_primary_subject) are generated automatically by the API. Do NOT add them manually tovalidators— they are redundant and may conflict with the auto-generated ones. Only pass validators that describe the event or topic, not entity filtering.start_dateandend_datefilter 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_datein pulled results.end_datemust be afterstart_date.Dates outside your plan lookback limits return API 400.
limitcontrols processed record count (cost-affecting). Omit it to retrieve everything up to your plan's maximum. If provided, must be >= 10.validators/enrichmentsmay be passed either as arrays or as JSON-string arrays (for client compatibility).validators[].typemust beboolean(if omitted, it defaults toboolean).enrichments[].typesupported 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_statusand callpull_results(partial results can appear before completion).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Optional job processing mode: `"lite"` (faster, lower cost, less detail) or `"base"` (default, full extraction). If omitted, the API defaults to `"base"`. | |
| limit | No | Optional processing cap (minimum 10); affects cost. Omit to retrieve everything up to your plan's maximum. | |
| query | Yes | Plain text search intent (required). | |
| schema | No | Optional advanced custom JSON schema string that overrides the default extraction schema. Use `initialize_query` to discover a suitable schema. | |
| api_key | No | CatchAll API key. Optional if provided via x-api-key header or CATCHALL_API_KEY env var. | |
| context | No | Optional guidance on what to prioritize (for example, target entities, event types, and specific data points you want captured in enrichments). If a company dataset will be attached, note that entity-relevance validators (e.g. `company_is_primary_subject`) will be auto-generated — do not ask for them here. Do not mention things like "company list will be attached". | |
| end_date | No | Optional ISO 8601 UTC end of search window. | |
| project_id | No | Optional project ID to associate this job with. | |
| start_date | No | Optional ISO 8601 UTC start of search window. | |
| validators | No | Optional custom boolean validators (`name`, `description`, `type`), as array or JSON-string array. When `connected_dataset_ids` is set, do NOT include entity-relevance validators such as `company_is_primary_subject` — the API generates those automatically. Only add validators that describe the event or topic (e.g. `is_acquisition_event`). | |
| enrichments | No | Optional custom enrichments (`name`, `description`, `type`), as array or JSON-string array. | |
| webhook_ids | No | Optional list of webhook IDs to notify when the job completes (max 5 per job). Use `list_webhooks` / `create_webhook` to get IDs. | |
| ed_score_min | No | Optional minimum entity-domain relevance score (1-10). Only relevant when `connected_dataset_ids` is set. | |
| ed_association_type | No | Optional filter on how strongly a watchlist entity must appear in each event. Only relevant when `connected_dataset_ids` is set. - `"event_associated"`: keep only events where the entity is a **direct actor** (default when connected_dataset_ids is set). - `"mention"`: keep all even where the entity is **merely referenced**. | |
| connected_dataset_ids | No | Optional list of dataset IDs whose entities narrow the retrieval scope. When set: (1) entity filtering is applied automatically — do NOT mention the company list or watchlist in `query`; (2) entity-relevance validators such as `company_is_primary_subject` are generated automatically — do NOT add them to `validators`. `ed_score_min` defaults to 2 if not provided. | |
| fetch_all_watchlist_news | No | When `True`, retrieves **all** news for connected watchlist entities without applying topic filtering from `query`. Requires `connected_dataset_ids` to be set. Default: `False`. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |