submit_query

com.newscatcherapi/catchall · Verify this server

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).