Company Watchlist

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

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"]
      }
    }
  }'

{
  "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"]
    }
  }
}

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

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;

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();

Show Create entity response

{
  "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.

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

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.

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.

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.

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"
      }
    }
  }'

{
  "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"
    }
  }
}

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

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;

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();

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

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"]
          }
        }
      }
    ]
  }'

{
  "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"]
        }
      }
    }
  ]
}

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]

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

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()
);

Show Create entities batch response

{
  "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.

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.

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"
    ]
  }'

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

dataset = client.datasets.create_dataset(
    name="My Portfolio",
    description="Companies we track for partnership activity",
    entity_ids=entity_ids,
)
dataset_id = dataset.id

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

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();

Show Create dataset response

{
  "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"
}

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.

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"

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"

dataset = client.datasets.create_dataset_from_csv(
    file=open("companies.csv", "rb"),
    name="My Portfolio",
)
dataset_id = dataset.dataset_id

import { createReadStream } from "fs";

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

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();

Show Create dataset from CSV response

{
  "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": []
  }
}

The CSV response returns dataset_id, not id. This differs from the JSON API path.

Wait for the dataset to be ready

Poll GET /catchAll/datasets/{dataset_id} until latest_status reaches ready. Do not submit a job before this step completes.

curl "https://catchall.newscatcherapi.com/catchAll/datasets/ccabb755-afc2-4047-b84c-78d1f23d49b2" \
  -H "x-api-key: YOUR_API_KEY"

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)

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));
}

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);
}

Show Get dataset response

{
  "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"
}

Submit a connected job

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

Only one dataset per job is supported at this time, even though connected_dataset_ids accepts an array.

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"]
  }'

{
  "query": "AI chip partnerships",
  "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"]
}

job = client.jobs.create_job(
    query="AI chip partnerships",
    connected_dataset_ids=[dataset_id],
)
job_id = job.job_id

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

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();

Poll GET /catchAll/status/{job_id} until status is completed, then retrieve results. See 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.

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"
  }'

{
  "query": "AI fundraising rounds",
  "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
  "ed_association_type": "event_associated"
}

job = client.jobs.create_job(
    query="AI fundraising rounds",
    connected_dataset_ids=[dataset_id],
    ed_association_type="event_associated",
)

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

var job = client.jobs().createJob(
    SubmitRequestDto.builder()
        .query("AI fundraising rounds")
        .connectedDatasetIds(List.of(datasetId))
        .edAssociationType(EntityAssociationType.EVENT_ASSOCIATED)
        .build()
);

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.

fetch_all_watchlist_news requires connected_dataset_ids to be set. Sending it without a connected watchlist returns a validation error.

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
  }'

{
  "query": "all news",
  "connected_dataset_ids": ["ccabb755-afc2-4047-b84c-78d1f23d49b2"],
  "fetch_all_watchlist_news": true
}

job = client.jobs.create_job(
    query="all news",
    connected_dataset_ids=[dataset_id],
    fetch_all_watchlist_news=True,
)

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

var job = client.jobs().createJob(
    SubmitRequestDto.builder()
        .query("all news")
        .connectedDatasetIds(List.of(datasetId))
        .fetchAllWatchlistNews(true)
        .build()
);

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.

curl "https://catchall.newscatcherapi.com/catchAll/pull/{job_id}" \
  -H "x-api-key: YOUR_API_KEY"

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}")

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}`);
  }
}

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());
        })
    );
});

Show Get results response

{
  "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"`.

Get started

Concepts

How to

API Reference

Libraries

Integrations

How it works

Create entities

Single entity

Writing effective descriptions

Attach an external entity ID

Batch

Create a dataset

From entity IDs

From CSV

Wait for the dataset to be ready

Submit a connected job

Filter by association type

Get all news for a watchlist

Get results

See also

​How it works

​Create entities

​Single entity

​Writing effective descriptions

​Attach an external entity ID

​Batch

​Create a dataset

​From entity IDs

​From CSV

​Wait for the dataset to be ready

​Submit a connected job

​Filter by association type

​Get all news for a watchlist

​Get results

​See also

How it works

Create entities

Single entity

Writing effective descriptions

Attach an external entity ID

Batch

Create a dataset

From entity IDs

From CSV

Wait for the dataset to be ready

Submit a connected job

Filter by association type

Get all news for a watchlist

Get results

See also