> ## Documentation Index
> Fetch the complete documentation index at: https://newscatcherinc-docs.mintlify.site/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Write effective queries

> Construct queries that produce high-quality event records.

Well-constructed queries determine the quality of your CatchAll results. This
guide shows you how to write queries that return focused, relevant events.

## Quick checklist

Before submitting a query, review these recommendations:

* [Describe real-world events](#describe-real-world-events) (not article retrieval)
* [Specify event type](#specify-event-type) (acquisitions, recalls, incidents)
* [Add 2-4 details](#add-2-4-details) (industry, amount, location)
* [Specify timeframe in your query](#specify-timeframe-in-your-query) (default 5 days, max depends on plan)
* [Keep queries focused](#keep-queries-focused) (single event type recommended)

<Tip>
  **Testing queries:** For quick testing, submit a job with the `limit`
  parameter to process fewer records (e.g., `limit: 10`). Once satisfied with
  the results, [continue the job](/web-search-api/api-reference/jobs/continue-job)
  or adjust the query and create a new job.
</Tip>

### What CatchAll finds

CatchAll, by design, focuses on identifying and extracting **real-world events**
— things that actually happen and get reported. The system queries a
continuously updated index of 2+ billion web pages, featuring time-sensitive,
event-driven content.

**CatchAll is for finding events:**

* Acquisitions, funding rounds, product launches
* Regulatory approvals, recalls, legal rulings
* Executive changes, layoffs, facility openings

**CatchAll is not for static content:**

* Product specifications or historical data tables
* Educational content, how-to guides, or reference material
* Evergreen articles or encyclopedic content

**CatchAll vs traditional web search:**

* **Traditional web search:** "Information about clinical trials" → Articles
  explaining what clinical trials are
* **CatchAll:** "Phase 3 clinical trial results for oncology drugs" → Every
  specific trial result with efficacy data, statistical significance, and trial
  identifiers

<CodeGroup>
  ```text ✅ Good queries (describe events) theme={null}
  Find all seed-round funding in the AI space over $5M in January 2026
  List all road infrastructure projects announced in the US, California
  Data breaches at financial institutions over the last week
  ```

  ```text ❌ Poor queries (request articles or static data) theme={null}
  Catch all news from CNBC since December 1
  (Requests articles, not events)

  Find articles about iPhone 15 features
  (Static product information, not events)

  Get historical GDP data by country
  (Data lookup, not events)
  ```
</CodeGroup>

## Specify event type

An **event** is something that happens and gets reported. CatchAll can only find
events that appear in published content—if something happens but isn't reported
anywhere, it's not observable to the system.

Target recognizable event types that get consistently reported:

| Event Category | Examples                                                         |
| -------------- | ---------------------------------------------------------------- |
| Business       | Acquisitions, mergers, IPOs, funding rounds, bankruptcies        |
| Corporate      | Layoffs, executive appointments, restructuring, earnings reports |
| Regulatory     | FDA approvals, product recalls, legal rulings, policy changes    |
| Technology     | Product launches, patent filings, security breaches              |
| Incidents      | Data breaches, workplace accidents, service outages              |
| Financial      | Credit downgrades, bond defaults, banking failures               |
| Infrastructure | Construction starts, facility openings, plant closures           |
| Legal          | Lawsuit filings, settlements, consent decrees                    |

<Note>
  This list is not exhaustive. CatchAll can find any event type that gets
  reported across authoritative web sources. If you can describe "what
  happened," CatchAll can find it.
</Note>

<CodeGroup>
  ```text ✅ Good queries theme={null}
  FDA drug approvals for rare diseases
  (Specific agency + event type + category)

  Tech company IPOs valued over $1B (Industry + event type + threshold)

  Executive departures at Fortune 500 companies (Event type + company category)

  ```

  ```text ❌ Poor queries theme={null}
  Tech industry trends
  (Analysis/commentary, not specific event)

  AI developments
  (Too vague—what kind of development?)

  Tesla news
  ("News" requests content, no event type specified)
  ```
</CodeGroup>

## Add 2-4 details

Balance breadth and focus. Too few details returns everything; too many details
returns nothing. Add 2-4 details like industry, threshold, or geography.

<CodeGroup>
  ```text ✅ Optimal (2-4 details) theme={null}
  AI company acquisitions over $50M
  (Event type + industry + threshold)

  Series B funding rounds for healthcare startups (Stage + industry)

  FDA drug approvals for oncology treatments (Agency + event type + medical field)

  ```

  ```text ❌ Too few details theme={null}
  Acquisitions
  (No industry, geography, or threshold—millions of potential results)

  Technology announcements
  (What kind of announcement? Product launch? Partnership? Earnings?)
  ```

  ```text ❌ Too many details theme={null}
  Series C funding rounds for AI cybersecurity companies
  in San Francisco over $100M announced on Tuesdays
  (7 details—very few results will match all constraints)
  ```
</CodeGroup>

<Tip>
  Use the `context` parameter for extraction preferences. Keep your `query`
  focused on the core event.
</Tip>

## Specify timeframe in your query

To scope your results to a specific period, include a timeframe in your query.
If you don't, the system uses a 5-day default. Your plan determines the maximum
search depth available to you.

You can also set the timeframe directly using `start_date` and `end_date` in
the request.

<Tip>
  To learn how search depth and date ranges work, see
  [Index and search depth](/web-search-api/concepts/index-and-search-depth).
</Tip>

<CodeGroup>
  ```text ✅ Good queries theme={null}
  Tech IPOs announced this week
  Recent cybersecurity incidents at healthcare companies
  AI model releases in the past month
  ```

  ```text ❌ Poor queries theme={null}
  AI funding rounds recently
  (Vague timeframe — use "last 7 days" or "this month" instead)

  Corporate bankruptcies since 2020
  (Multi-year range — likely exceeds plan's search depth)
  ```
</CodeGroup>

<Note>
  For monitors, the system automatically adapts time-based filters for recurring
  execution. See [Configure monitors](/web-search-api/how-to/configure-monitors)
  for monitor-specific guidance.
</Note>

## Keep queries focused

Focused queries produce cleaner, more useful results. If your query combines
multiple entities or event types, consider splitting it into separate queries.

<CodeGroup>
  ```text ✅ Recommended: Single event type theme={null}
  Apple acquisitions in AI sector
  (Focused on one company's M&A activity)

  Data breaches at healthcare companies (Focused on security incidents in one
  industry)

  Series B funding rounds for fintech startups (Focused on one funding stage in
  one sector)

  ```

  ```text ⚠️ Works, but consider splitting theme={null}
  Acquisitions by Apple, Microsoft, and Google
  (Mixed results - three different companies' strategies)

  Better approach:
  - Query 1: Apple acquisitions
  - Query 2: Microsoft acquisitions
  - Query 3: Google acquisitions
  ```

  ```text ❌ Difficult to work with theme={null}
  Apple acquisitions and Microsoft layoffs
  (Mixes two different event types)

  Acquisitions by Apple, layoffs at Meta, or IPOs from AI startups
  (Mixes three companies and three event types)

  Better approach: Split into focused queries for each event type.
  ```
</CodeGroup>

## See also

* [Quickstart guide](/web-search-api/get-started/quickstart)
* [Configure monitors](/web-search-api/how-to/configure-monitors)
* [Dynamic schemas](/web-search-api/concepts/dynamic-schemas)