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

# Company Watchlist

> Track specific companies across CatchAll jobs with per-company relevance scores.

Company Watchlist filters CatchAll job results to a predefined list of companies
and scores each matching record per company. Use it to track specific companies —
a portfolio, a competitor set, or any curated list — instead of running broad queries.

## How it works

Company Watchlist uses three connected concepts:

**Entities** are individual company definitions. Each entity stores identifying
information — name, domain, description, alternative names, key persons — that the system
uses to recognize the company in web content.

**Datasets** are named collections of entities. A dataset acts as a watchlist or
portfolio. You create it once and can reuse it across multiple jobs and monitors.

**Connected jobs** are standard CatchAll jobs submitted with a
`connected_dataset_ids` parameter. Adding this parameter activates company
search mode; everything else about the job — query, validators, enrichments,
date ranges — works identically to a normal job.

## Create entities

The `name` field is required. You must also provide at least one of `description`
or `domain` (inside `additional_attributes.company_attributes`).
Matching quality depends on what you provide. `domain` and `description` are the most reliable
signals:

* Two companies can share a name, but not a domain.
* Companies might have the same name, but they usually operate in different sectors. That's why description is the key to a proper disambiguation

### Single entity

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/entities" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "NewsCatcher",
      "entity_type": "company",
      "description": "NewsCatcher is a data-as-a-service company headquartered in Middletown, Delaware, USA, founded in 2021, providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).",
      "additional_attributes": {
        "company_attributes": {
          "domain": "newscatcherapi.com",
          "alternative_names": ["NewsCatcher API", "NewsCatcher CatchAll"],
          "key_persons": ["Artem Bugara", "Maksym Sugonyaka"]
        }
      }
    }'
  ```

  ```json JSON theme={null}
  {
    "name": "NewsCatcher",
    "entity_type": "company",
    "description": "NewsCatcher is a data-as-a-service company headquartered in Middletown, Delaware, USA, founded in 2021, providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).",
    "additional_attributes": {
      "company_attributes": {
        "domain": "newscatcherapi.com",
        "alternative_names": ["NewsCatcher API", "NewsCatcher CatchAll"],
        "key_persons": ["Artem Bugara", "Maksym Sugonyaka"]
      }
    }
  }
  ```

  ```python Python theme={null}
  from newscatcher_catchall import (
      CatchAllApi,
      AdditionalAttributes,
      CompanyAttributes,
  )

  client = CatchAllApi(api_key="YOUR_API_KEY")

  entity = client.entities.create_entity(
      name="NewsCatcher",
      entity_type="company",
      description="NewsCatcher is a data-as-a-service company headquartered in Middletown, Delaware, USA, founded in 2021, providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).",
      additional_attributes=AdditionalAttributes(
          company_attributes=CompanyAttributes(
              domain="newscatcherapi.com",
              alternative_names=["NewsCatcher CatchAll", "NewsCatcher API"],
              key_persons=["Artem Bugara", "Maksym Sugonyaka"],
          )
      ),
  )
  entity_id = entity.id
  ```

  ```typescript TypeScript theme={null}
  import { CatchAllApiClient } from "newscatcher-catchall-sdk";

  const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

  const entity = await client.entities.createEntity({
    name: "NewsCatcher",
    entity_type: "company",
    description: "NewsCatcher is a data-as-a-service company headquartered in Middletown, Delaware, USA, founded in 2021, providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).",
    additional_attributes: {
      company_attributes: {
        domain: "newscatcherapi.com",
        alternative_names: ["NewsCatcher CatchAll", "NewsCatcher API"],
        key_persons: ["Artem Bugara", "Maksym Sugonyaka"],
      },
    },
  });
  const entityId = entity.id;
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.CatchAllApi;
  import com.newscatcher.catchall.types.*;
  import java.util.List;

  CatchAllApi client = CatchAllApi.builder()
      .apiKey("YOUR_API_KEY")
      .build();

  CreateEntityResponse entity = client.entities().createEntity(
      CreateEntityRequest.builder()
          .name("NewsCatcher")
          .entityType(EntityType.COMPANY)
          .description("NewsCatcher is a data-as-a-service company headquartered in Middletown, Delaware, USA, founded in 2021, providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).")
          .additionalAttributes(AdditionalAttributes.builder()
              .companyAttributes(CompanyAttributes.builder()
                  .domain("newscatcherapi.com")
                  .alternativeNames(List.of("NewsCatcher CatchAll", "NewsCatcher API"))
                  .keyPersons(List.of("Artem Bugara", "Maksym Sugonyaka"))
                  .build())
              .build())
          .build()
  );
  String entityId = entity.getId();
  ```
</CodeGroup>

<Expandable title="Create entity response">
  ```json theme={null}
  {
    "id": "854198fa-f702-49db-a381-0427fa87f173",
    "status": "pending"
  }
  ```

  Entities move through `pending → enriching → ready` (or `failed`) after
  creation. You don't need to wait for individual entities to be ready before
  creating a dataset — the dataset status is what matters before submitting a job.

  <Note>
    External enrichment is not yet active. Entities move directly to `ready`
    based on the fields you supply. This will change in a future release.
  </Note>
</Expandable>

### Writing effective descriptions

The `description` field is the primary signal used to tell two companies with
the same name apart. A specific, factual description gives the matching model
distinctive features to anchor on — vague, marketing-style text produces false
positives or missed coverage.

The goal is to **fingerprint** the company, not to sell it. Aim for two to four
sentences covering **what the company is** and **what it offers**.

**Good description:**

> Apollo Global Management is a US-based alternative
> asset management firm headquartered in New York City, founded in 1990 by
> Leon Black, Marc Rowan, and Josh Harris. It manages private equity, credit,
> and real assets funds with over \$650 billion in assets under management and
> is publicly traded on the NYSE under the ticker APO.

**Bad description:**

> Apollo is a global leader providing innovative solutions to clients across
> multiple industries worldwide.

The bad example fits dozens of companies named Apollo equally well. Consider
two real ones: **Apollo Global Management** (New York City; alternative asset
management; founded 1990; NYSE: APO) and **Apollo Hospitals** (Chennai, India;
private hospital chain; founded 1983 by Dr. Prathap C. Reddy; largest private
hospital network in Asia). The name alone tells you nothing — what separates
them is geography, industry, founders, and products. The same pattern applies
to "Delta" (airline vs. faucets vs. dental insurance) and "Dove" (Unilever
personal care vs. Mars chocolate).

The details that do the disambiguation work are: **aliases**, **specific
industry**, **headquarters location**, **founding year and founders**, and
**concrete products or services**. Generic adjectives ("leading," "innovative,"
"world-class") carry no disambiguating signal — drop them.

<Tip>
  Before saving: *Could this description be true of a different company with the
  same name?* If yes, add the attribute that breaks the tie — usually industry,
  geography, or flagship products.
</Tip>

A complete description includes:

* Full legal name
* Specific industry or sector — not "technology" but "freight forwarding and customs brokerage"
* Headquarters city and country, plus main regions of operation
* Concrete products, services, and brand names
* Parent company, subsidiaries, ticker, or public/private status when relevant

### Attach an external entity ID

Use the optional `external_entity_id` field to store your own identifier for an
entity — a CRM, data warehouse, or internal database ID. CatchAll stores it as
provided and returns it on entity responses, dataset entity summaries, and
connected entities in job results, so you can join CatchAll output back to your
systems without maintaining a separate mapping.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/entities" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "NewsCatcher",
      "entity_type": "company",
      "description": "NewsCatcher is a data-as-a-service company providing news intelligence APIs.",
      "external_entity_id": "crm-12345",
      "additional_attributes": {
        "company_attributes": {
          "domain": "newscatcherapi.com"
        }
      }
    }'
  ```

  ```json JSON theme={null}
  {
    "name": "NewsCatcher",
    "entity_type": "company",
    "description": "NewsCatcher is a data-as-a-service company providing news intelligence APIs.",
    "external_entity_id": "crm-12345",
    "additional_attributes": {
      "company_attributes": {
        "domain": "newscatcherapi.com"
      }
    }
  }
  ```

  ```python Python theme={null}
  from newscatcher_catchall import (
      CatchAllApi,
      AdditionalAttributes,
      CompanyAttributes,
  )

  client = CatchAllApi(api_key="YOUR_API_KEY")

  entity = client.entities.create_entity(
      name="NewsCatcher",
      entity_type="company",
      description="NewsCatcher is a data-as-a-service company providing news intelligence APIs.",
      external_entity_id="crm-12345",
      additional_attributes=AdditionalAttributes(
          company_attributes=CompanyAttributes(
              domain="newscatcherapi.com",
          )
      ),
  )
  entity_id = entity.id
  ```

  ```typescript TypeScript theme={null}
  import { CatchAllApiClient } from "newscatcher-catchall-sdk";

  const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

  const entity = await client.entities.createEntity({
    name: "NewsCatcher",
    entity_type: "company",
    description: "NewsCatcher is a data-as-a-service company providing news intelligence APIs.",
    external_entity_id: "crm-12345",
    additional_attributes: {
      company_attributes: {
        domain: "newscatcherapi.com",
      },
    },
  });
  const entityId = entity.id;
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.CatchAllApi;
  import com.newscatcher.catchall.types.*;

  CatchAllApi client = CatchAllApi.builder()
      .apiKey("YOUR_API_KEY")
      .build();

  CreateEntityResponse entity = client.entities().createEntity(
      CreateEntityRequest.builder()
          .name("NewsCatcher")
          .entityType(EntityType.COMPANY)
          .description("NewsCatcher is a data-as-a-service company providing news intelligence APIs.")
          .externalEntityId("crm-12345")
          .additionalAttributes(AdditionalAttributes.builder()
              .companyAttributes(CompanyAttributes.builder()
                  .domain("newscatcherapi.com")
                  .build())
              .build())
          .build()
  );
  String entityId = entity.getId();
  ```
</CodeGroup>

The value is a free-form string of up to 255 characters and is **not** enforced
as unique — CatchAll does not deduplicate entities by it. You can set it when
creating an entity (single or batch) and change it later with
[`PATCH /catchAll/entities/{entity_id}`](/docs/web-search-api/api-reference/entities/update-entity).
When no value is set, the field is returned as `null`.

### Batch

Use batch creation when adding multiple entities at once. Each entity is
processed independently — one failure does not affect the others.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/entities/batch" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "entities": [
        {
          "name": "NewsCatcher",
          "entity_type": "company",
          "additional_attributes": {
            "company_attributes": { "domain": "newscatcherapi.com" }
          }
        },
        {
          "name": "OpenAI",
          "entity_type": "company",
          "additional_attributes": {
            "company_attributes": {
              "domain": "openai.com",
              "key_persons": ["Sam Altman"]
            }
          }
        }
      ]
    }'
  ```

  ```json JSON theme={null}
  {
    "entities": [
      {
        "name": "NewsCatcher",
        "entity_type": "company",
        "additional_attributes": {
          "company_attributes": { "domain": "newscatcherapi.com" }
        }
      },
      {
        "name": "OpenAI",
        "entity_type": "company",
        "additional_attributes": {
          "company_attributes": {
            "domain": "openai.com",
            "key_persons": ["Sam Altman"]
          }
        }
      }
    ]
  }
  ```

  ```python Python theme={null}
  from newscatcher_catchall import (
      CatchAllApi,
      AdditionalAttributes,
      CompanyAttributes,
      CreateEntityRequest,
  )

  client = CatchAllApi(api_key="YOUR_API_KEY")

  result = client.entities.create_entities_batch(
      entities=[
          CreateEntityRequest(
              name="NewsCatcher",
              entity_type="company",
              additional_attributes=AdditionalAttributes(
                  company_attributes=CompanyAttributes(
                      domain="newscatcherapi.com",
                  )
              ),
          ),
          CreateEntityRequest(
              name="OpenAI",
              entity_type="company",
              additional_attributes=AdditionalAttributes(
                  company_attributes=CompanyAttributes(
                      domain="openai.com",
                      key_persons=["Sam Altman"],
                  )
              ),
          ),
      ],
  )
  entity_ids = [e.id for e in result.entities]
  ```

  ```typescript TypeScript theme={null}
  import { CatchAllApiClient } from "newscatcher-catchall-sdk";

  const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });

  const result = await client.entities.createEntitiesBatch({
    entities: [
      {
        name: "NewsCatcher",
        entity_type: "company",
        additional_attributes: {
          company_attributes: { domain: "newscatcherapi.com" },
        },
      },
      {
        name: "OpenAI",
        entity_type: "company",
        additional_attributes: {
          company_attributes: {
            domain: "openai.com",
            key_persons: ["Sam Altman"],
          },
        },
      },
    ],
  });
  const entityIds = result.entities.map((e) => e.id);
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.CatchAllApi;
  import com.newscatcher.catchall.resources.entities.requests.CreateEntitiesBatchRequest;
  import com.newscatcher.catchall.types.*;
  import java.util.List;

  CatchAllApi client = CatchAllApi.builder()
      .apiKey("YOUR_API_KEY")
      .build();

  CreateEntitiesBatchResponse result = client.entities().createEntitiesBatch(
      CreateEntitiesBatchRequest.builder()
          .entities(List.of(
              CreateEntityRequest.builder()
                  .name("NewsCatcher")
                  .entityType(EntityType.COMPANY)
                  .additionalAttributes(AdditionalAttributes.builder()
                      .companyAttributes(CompanyAttributes.builder()
                          .domain("newscatcherapi.com")
                          .build())
                      .build())
                  .build(),
              CreateEntityRequest.builder()
                  .name("OpenAI")
                  .entityType(EntityType.COMPANY)
                  .additionalAttributes(AdditionalAttributes.builder()
                      .companyAttributes(CompanyAttributes.builder()
                          .domain("openai.com")
                          .keyPersons(List.of("Sam Altman"))
                          .build())
                      .build())
                  .build()
          ))
          .build()
  );
  ```
</CodeGroup>

<Expandable title="Create entities batch response">
  ```json theme={null}
  {
    "entities": [
      {
        "id": "854198fa-f702-49db-a381-0427fa87f173",
        "status": "pending"
      },
      {
        "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "status": "pending"
      }
    ],
    "count": 2
  }
  ```

  Results are returned in the same order as the input array.
</Expandable>

## Create a dataset

### From entity IDs

Create a dataset from existing entity IDs. All IDs must belong to your
organization — any invalid ID returns `400`.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/datasets" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "name": "My Portfolio",
      "description": "Companies we track for partnership activity",
      "entity_ids": [
        "854198fa-f702-49db-a381-0427fa87f173",
        "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      ]
    }'
  ```

  ```json JSON theme={null}
  {
    "name": "My Portfolio",
    "description": "Companies we track for partnership activity",
    "entity_ids": [
      "854198fa-f702-49db-a381-0427fa87f173",
      "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    ]
  }
  ```

  ```python Python theme={null}
  dataset = client.datasets.create_dataset(
      name="My Portfolio",
      description="Companies we track for partnership activity",
      entity_ids=entity_ids,
  )
  dataset_id = dataset.id
  ```

  ```typescript TypeScript theme={null}
  const dataset = await client.datasets.createDataset({
    name: "My Portfolio",
    description: "Companies we track for partnership activity",
    entity_ids: entityIds,
  });
  const datasetId = dataset.id;
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.resources.datasets.requests.CreateDatasetRequest;
  import com.newscatcher.catchall.types.DatasetResponse;

  DatasetResponse dataset = client.datasets().createDataset(
      CreateDatasetRequest.builder()
          .name("My Portfolio")
          .description("Companies we track for partnership activity")
          .entityIds(entityIds)
          .build()
  );
  String datasetId = dataset.getId();
  ```
</CodeGroup>

<Expandable title="Create dataset response">
  ```json theme={null}
  {
    "id": "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    "organization_id": "org_6f3a2b1c",
    "name": "My Portfolio",
    "description": "Companies we track for partnership activity",
    "entity_count": 2,
    "latest_status": "pending",
    "created_at": "2026-04-10T09:00:00Z",
    "updated_at": "2026-04-10T09:00:00Z"
  }
  ```
</Expandable>

### From CSV

Upload a CSV to create both entities and the dataset in a single request —
the fastest path for most use cases.

The `name` and `domain` columns are required; all other columns are optional.
Use semicolons to separate multiple values in `alternative_names` and `key_persons`.
Rows with an empty `name` are skipped and reported in `validation_report`.

```csv theme={null}
name,description,domain,alternative_names,key_persons
NewsCatcher,"NewsCatcher is a data-as-a-service company headquartered in Middletown, Delaware, USA, founded in 2021, providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).",newscatcherapi.com,"NewsCatcher CatchAll;NewsCatcher API","Artem Bugara;Maksym Sugonyaka"
OpenAI,"Artificial intelligence research company",openai.com,"Open AI","Sam Altman"
Stripe,"Online payments platform",stripe.com,"","Patrick Collison;John Collison"
```

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/datasets/upload" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "file=@companies.csv" \
    -F "name=My Portfolio"
  ```

  ```python Python theme={null}
  dataset = client.datasets.create_dataset_from_csv(
      file=open("companies.csv", "rb"),
      name="My Portfolio",
  )
  dataset_id = dataset.dataset_id
  ```

  ```typescript TypeScript theme={null}
  import { createReadStream } from "fs";

  const dataset = await client.datasets.createDatasetFromCsv({
    file: createReadStream("companies.csv"),
    name: "My Portfolio",
  });
  const datasetId = dataset.dataset_id;
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.resources.datasets.requests.CreateDatasetFromCsvRequest;
  import com.newscatcher.catchall.types.CreateDatasetCsvResponse;
  import java.io.File;

  CreateDatasetCsvResponse dataset = client.datasets().createDatasetFromCsv(
      new File("companies.csv"),
      CreateDatasetFromCsvRequest.builder()
          .name("My Portfolio")
          .build()
  );
  String datasetId = dataset.getDatasetId();
  ```
</CodeGroup>

<Expandable title="Create dataset from CSV response">
  ```json theme={null}
  {
    "dataset_id": "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    "dataset_name": "My Portfolio",
    "entities_created": 3,
    "validation_report": {
      "total_rows": 3,
      "valid_rows": 3,
      "skipped_count": 0,
      "skipped_rows": []
    }
  }
  ```

  <Note>
    The CSV response returns `dataset_id`, not `id`. This differs from the JSON
    API path.
  </Note>
</Expandable>

## Wait for the dataset to be ready

Poll [`GET /catchAll/datasets/{dataset_id}`](/docs/web-search-api/api-reference/datasets/get-dataset)
until `latest_status` reaches `ready`. Do not submit a job before this step
completes.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://catchall.newscatcherapi.com/catchAll/datasets/ccabb755-afc2-4047-b84c-78d1f23d49b2" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  import time

  POLL_INTERVAL = 5  # seconds

  while True:
      status = client.datasets.get_dataset(dataset_id)
      if status.latest_status == "ready":
          break
      if status.latest_status == "failed":
          raise RuntimeError("Dataset processing failed")
      time.sleep(POLL_INTERVAL)
  ```

  ```typescript TypeScript theme={null}
  const POLL_INTERVAL_MS = 5000;

  while (true) {
    const status = await client.datasets.getDataset({ dataset_id: datasetId });
    if (status.latest_status === "ready") break;
    if (status.latest_status === "failed") {
      throw new Error("Dataset processing failed");
    }
    await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
  }
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.types.DatasetResponse;
  import com.newscatcher.catchall.types.DatasetStatus;
  import java.util.concurrent.TimeUnit;

  while (true) {
      DatasetResponse status = client.datasets().getDataset(datasetId);
      if (DatasetStatus.READY.equals(status.getLatestStatus().orElse(null))) break;
      if (DatasetStatus.FAILED.equals(status.getLatestStatus().orElse(null))) {
          throw new RuntimeException("Dataset processing failed");
      }
      TimeUnit.SECONDS.sleep(5);
  }
  ```
</CodeGroup>

<Expandable title="Get dataset response">
  ```json theme={null}
  {
    "id": "ccabb755-afc2-4047-b84c-78d1f23d49b2",
    "organization_id": "org_6f3a2b1c",
    "name": "My Portfolio",
    "description": "Companies we track for partnership activity",
    "entity_count": 2,
    "entity_status_breakdown": {
      "ready": 2
    },
    "health_score": 100,
    "health_breakdown": {
      "company": 100
    },
    "latest_status": "ready",
    "created_at": "2026-04-10T09:00:00Z",
    "updated_at": "2026-04-10T09:00:05Z"
  }
  ```
</Expandable>

## Submit a connected job

Add `connected_dataset_ids` to a standard job submission to activate company
search mode:

<Note>
  Only one dataset per job is supported at this time, even though
  `connected_dataset_ids` accepts an array.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "AI chip partnerships",
      "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"]
    }'
  ```

  ```json JSON theme={null}
  {
    "query": "AI chip partnerships",
    "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"]
  }
  ```

  ```python Python theme={null}
  job = client.jobs.create_job(
      query="AI chip partnerships",
      connected_dataset_ids=[dataset_id],
  )
  job_id = job.job_id
  ```

  ```typescript TypeScript theme={null}
  const job = await client.jobs.createJob({
    query: "AI chip partnerships",
    connected_dataset_ids: [datasetId],
  });
  const jobId = job.job_id;
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.resources.jobs.requests.SubmitRequestDto;
  import java.util.List;

  var job = client.jobs().createJob(
      SubmitRequestDto.builder()
          .query("AI chip partnerships")
          .connectedDatasetIds(List.of(datasetId))
          .build()
  );
  String jobId = job.getJobId();
  ```
</CodeGroup>

Poll [`GET /catchAll/status/{job_id}`](/docs/web-search-api/api-reference/jobs/get-job-status)
until `status` is `completed`, then retrieve results. See
[Jobs](/docs/web-search-api/concepts/jobs) for the polling pattern.

## Filter by association type

When a job is connected to a dataset, you can control how strictly entities must
relate to each result by setting `ed_association_type`.

| Value              | Behavior                                                                                                                                                                  |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_associated` | Only returns events where a tracked entity is the primary actor — the company that raised funding, was acquired, announced layoffs, etc. Passing references are excluded. |
| `mention`          | Returns any event where a tracked entity appears, whether as a primary actor or a passing reference.                                                                      |

When omitted, no association-type filter is applied and all matching records are
returned regardless of how the entity relates to the event.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "AI fundraising rounds",
      "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
      "ed_association_type": "event_associated"
    }'
  ```

  ```json JSON theme={null}
  {
    "query": "AI fundraising rounds",
    "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
    "ed_association_type": "event_associated"
  }
  ```

  ```python Python theme={null}
  job = client.jobs.create_job(
      query="AI fundraising rounds",
      connected_dataset_ids=[dataset_id],
      ed_association_type="event_associated",
  )
  ```

  ```typescript TypeScript theme={null}
  const job = await client.jobs.createJob({
    query: "AI fundraising rounds",
    connected_dataset_ids: [datasetId],
    ed_association_type: "event_associated",
  });
  ```

  ```java Java theme={null}
  var job = client.jobs().createJob(
      SubmitRequestDto.builder()
          .query("AI fundraising rounds")
          .connectedDatasetIds(List.of(datasetId))
          .edAssociationType(EntityAssociationType.EVENT_ASSOCIATED)
          .build()
  );
  ```
</CodeGroup>

Each matched entity in the results includes an `association_type` field
(`event_associated` or `mention`) indicating how it relates to that specific
record.

## Get all news for a watchlist

To retrieve all news about your tracked companies without filtering by a
specific topic, set `fetch_all_watchlist_news: true`. Use this when you want a
broad news feed for a portfolio or competitor set rather than a targeted event
search.

Wildcard queries (`*`) and generic phrases like "all news" also trigger this
behavior automatically.

<Note>
  `fetch_all_watchlist_news` requires `connected_dataset_ids` to be set.
  Sending it without a connected watchlist returns a validation error.
</Note>

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "all news",
      "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
      "fetch_all_watchlist_news": true
    }'
  ```

  ```json JSON theme={null}
  {
    "query": "all news",
    "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
    "fetch_all_watchlist_news": true
  }
  ```

  ```python Python theme={null}
  job = client.jobs.create_job(
      query="all news",
      connected_dataset_ids=[dataset_id],
      fetch_all_watchlist_news=True,
  )
  ```

  ```typescript TypeScript theme={null}
  const job = await client.jobs.createJob({
    query: "all news",
    connected_dataset_ids: [datasetId],
    fetch_all_watchlist_news: true,
  });
  ```

  ```java Java theme={null}
  var job = client.jobs().createJob(
      SubmitRequestDto.builder()
          .query("all news")
          .connectedDatasetIds(List.of(datasetId))
          .fetchAllWatchlistNews(true)
          .build()
  );
  ```
</CodeGroup>

Monitors created from an all-news job preserve this behavior — each recurring
run collects all news for the connected watchlist, not topic-restricted results.

## Get results

Retrieve results the same way as a normal job. Each record includes a
`connected_entities` array with one entry per matched company. Entities with
`ed_score` of 0 are filtered out automatically and never appear.

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://catchall.newscatcherapi.com/catchAll/pull/{job_id}" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```python Python theme={null}
  results = client.jobs.get_job_results(job_id)

  for record in results.all_records:
      print(record.record_title)
      for entity in record.connected_entities:
          print(f"  {entity.name} — score {entity.ed_score}/10")
          print(f"  {entity.relation}")
  ```

  ```typescript TypeScript theme={null}
  const results = await client.jobs.getJobResults({ job_id: jobId });

  for (const record of results.all_records) {
    console.log(record.record_title);
    for (const entity of record.connected_entities ?? []) {
      console.log(`  ${entity.name} — score ${entity.ed_score}/10`);
      console.log(`  ${entity.relation}`);
    }
  }
  ```

  ```java Java theme={null}
  import com.newscatcher.catchall.types.PullJobResponseDto;

  PullJobResponseDto results = client.jobs().getJobResults(jobId);

  results.getAllRecords().forEach(record -> {
      System.out.println(record.getRecordTitle());
      record.getConnectedEntities().ifPresent(entities ->
          entities.forEach(entity -> {
              System.out.printf("  %s — score %.0f/10%n",
                  entity.getName(), entity.getEdScore());
              System.out.println("  " + entity.getRelation());
          })
      );
  });
  ```
</CodeGroup>

<Expandable title="Get results response">
  ```json theme={null}
  {
    "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
    "query": "AI chip partnerships",
    "status": "completed",
    "valid_records": 1,
    "all_records": [
      {
        "record_id": "6417909601438475967",
        "record_title": "NVIDIA Expands AI Infrastructure Partnership with NewsCatcher",
        "enrichment": {
          "partnership_type": "technology integration",
          "deal_stage": "announced",
          "enrichment_confidence": "high"
        },
        "citations": [
          {
            "title": "NVIDIA Announces New AI Data Partners",
            "link": "https://example.com/nvidia-ai-partners",
            "published_date": "2026-04-10T09:00:00Z"
          }
        ],
        "connected_entities": [
          {
            "entity_id": "854198fa-f702-49db-a381-0427fa87f173",
            "name": "NewsCatcher",
            "type": "company",
            "ed_score": 9,
            "association_type": "event_associated",
            "relation": "NewsCatcher is a named partner in the announced AI infrastructure deal",
            "company": {
              "domain": "newscatcherapi.com",
              "description": "NewsCatcher is a data-as-a-service company headquartered in Middletown, Delaware, USA, founded in 2021, providing news intelligence APIs including the CatchAll Web Search API (2B+ web pages indexed) and News API (140,000+ sources, 100+ countries).",
              "alternative_names": [
                "NewsCatcher CatchAll",
                "NewsCatcher API"
              ],
              "key_persons": [
                "Artem Bugara",
                "Maksym Sugonyaka"
              ]
            }
          }
        ]
      }
    ]
  }
  ```

  **`connected_entities` fields:**

  | Field              | Type   | Notes                                                                                                    |
  | ------------------ | ------ | -------------------------------------------------------------------------------------------------------- |
  | `entity_id`        | string | UUID of the matched entity                                                                               |
  | `name`             | string | Entity name                                                                                              |
  | `type`             | string | Entity type, e.g. `company`                                                                              |
  | `ed_score`         | number | Relevance score from 1 to 10                                                                             |
  | `association_type` | string | How the entity relates to the event: `event_associated` (primary actor) or `mention` (passing reference) |
  | `relation`         | string | Sentence describing how this entity relates to the record. Maximum 100 characters.                       |
  | `company`          | object | Company-specific attributes (domain, alternative names, key persons). Present when `type == "company"`.  |
</Expandable>

## See also

* [Jobs](/docs/web-search-api/concepts/jobs)
* [Monitors](/docs/web-search-api/concepts/monitors)
* [Entities API reference](/docs/web-search-api/api-reference/entities/create-entity)
* [Datasets API reference](/docs/web-search-api/api-reference/datasets/create-dataset)