Jobs

A job is the core unit of work in CatchAll. You submit a query, CatchAll processes it asynchronously, and you retrieve structured JSON records when the job completes.

Jobs lifecycle

Job lifecycle diagram showing three flows: Basic (initialize optional → submit → get status → pull results), Continue (continue → get status → pull results, extends a job submitted with limit), and Audit (list user jobs, returns all jobs for your API key).

Initialize job

POST /catchAll/initialize analyzes your query and returns LLM-generated suggestions for validators, enrichments, and a date range. It does not create a job or start processing. This endpoint is a preview — it shows you one example of what validators and enrichments could look like for your query. Because the suggestions are LLM-generated, they are not deterministic. If you call initialize and then submit a job without passing any validators or enrichments, the system generates them again from scratch and the results will differ from the initialize response. To use the initialize suggestions in your job, pass them explicitly in your submit request. You can use them as-is, modify them, or write your own.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/initialize" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Series B funding rounds for SaaS startups",
    "context": "Focus on funding amount and company name"
  }'

Show Initialize job response

{
  "validators": [
    {
      "name": "is_series_b_funding",
      "description": "true if the article describes a Series B funding round",
      "type": "boolean"
    },
    {
      "name": "is_saas_startup",
      "description": "true if the company receiving funding is a SaaS startup",
      "type": "boolean"
    }
  ],
  "enrichments": [
    {
      "name": "funding_amount",
      "description": "Extract the amount of funding received in the Series B round",
      "type": "number"
    },
    {
      "name": "investee_company",
      "description": "Extract the name of the SaaS startup receiving the funding",
      "type": "company"
    },
    {
      "name": "investor_company",
      "description": "Extract the name of the investor or lead investor in the funding round",
      "type": "company"
    },
    {
      "name": "funding_date",
      "description": "Extract the date when the funding round was announced",
      "type": "date"
    }
  ],
  "start_date": "2026-02-19T13:56:37.254913+00:00",
  "end_date": "2026-02-24T13:56:37.254913+00:00",
  "date_modification_message": [
    "No dates were provided; using a default window of 5 days (2026-02-19 13:56:37 to 2026-02-24 13:56:37)."
  ]
}

Create job

POST /catchAll/submit creates the job and starts processing. Only query is required — all other parameters are optional.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/submit" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Series B funding rounds for SaaS startups",
    "context": "Focus on funding amount and company name",
    "start_date": "2026-02-18T00:00:00Z",
    "end_date": "2026-02-23T00:00:00Z",
    "limit": 10
  }'

Show Create job response

{
  "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c"
}

Use limit: 10 for quick testing. If the results look good, use Continue job to process more records without restarting.

Get job status

GET /catchAll/status/{job_id} returns the current processing stage. Poll every 30-60 seconds until status is completed. Jobs typically take 10-15 minutes. Jobs progress through these stages in order:

Stage	Description
`submitted`	Job queued, waiting to start
`analyzing`	Generating search queries, validators, and enrichments
`fetching`	Retrieving web pages
`clustering`	Grouping related web pages into event clusters
`enriching`	Validating clusters and extracting structured data
`completed`	Processing finished, results ready
`failed`	Processing failed

curl "https://catchall.newscatcherapi.com/catchAll/status/5f0c9087-85cb-4917-b3c7-e5a5eff73a0c" \
  -H "x-api-key: YOUR_API_KEY"

Show Get job status response

{
  "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
  "status": "completed",
  "steps": [
    {
      "status": "submitted",
      "order": 1,
      "completed": true
    },
    {
      "status": "analyzing",
      "order": 2,
      "completed": true
    },
    {
      "status": "fetching",
      "order": 3,
      "completed": true
    },
    {
      "status": "clustering",
      "order": 4,
      "completed": true
    },
    {
      "status": "enriching",
      "order": 5,
      "completed": true
    },
    {
      "status": "completed",
      "order": 6,
      "completed": true
    },
    {
      "status": "failed",
      "order": 7,
      "completed": false
    }
  ]
}

You can pull partial results once the job reaches the enriching stage without waiting for completion. See Get job results below.

Get job results

GET /catchAll/pull/{job_id} retrieves structured records. During the enriching stage, progress_validated tracks how many candidate clusters have been processed so far.

curl "https://catchall.newscatcherapi.com/catchAll/pull/5f0c9087-85cb-4917-b3c7-e5a5eff73a0c" \
  -H "x-api-key: YOUR_API_KEY"

Show Get job results response

{
  "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
  "query": "Series B funding rounds for SaaS startups",
  "context": "Focus on funding amount and company name",
  "validators": [
    "is_series_b",
    "involves_saas_startup",
    "is_about_funding_round",
    "mentions_funding_amount"
  ],
  "enrichments": [
    "funding_amount",
    "funding_currency",
    "investee_company",
    "investor_company",
    "announcement_date",
    "saas_category",
    "valuation",
    "other_investors"
  ],
  "status": "completed",
  "duration": "1m",
  "candidate_records": 4,
  "valid_records": 3,
  "progress_validated": 4,
  "date_range": {
    "start_date": "2026-02-17T00:00:00Z",
    "end_date": "2026-02-24T00:00:00Z"
  },
  "page": 1,
  "page_size": 2,
  "total_pages": 2,
  "all_records": [
    {
      "record_id": "6983973854314692457",
      "record_title": "VulnCheck Raises $25M Series B Funding",
      "enrichment": {
        "confidence": "high",
        "saas_category": "cybersecurity",
        "funding_amount": 25000000,
        "funding_currency": "USD",
        "announcement_date": "2026-02-17",
        "investee_company": {
          "source_text": "VulnCheck",
          "confidence": 0.99,
          "metadata": {
            "name": "VulnCheck",
            "domain_url": "vulncheck.com",
            "confidence": "high"
          }
        },
        "investor_company": {
          "source_text": "Sorenson Capital",
          "confidence": 0.99,
          "metadata": {
            "name": "Sorenson Capital",
            "domain_url": null,
            "confidence": null
          }
        },
        "valuation": 25000000,
        "other_investors": "National Grid Partners, Ten Eleven Ventures, In-Q-Tel"
      },
      "citations": [
        {
          "title": "Exclusive: VulnCheck raises $25M funding to help companies patch software bugs",
          "link": "https://www.msn.com/en-us/money/other/exclusive-vulncheck-raises-25m-funding-to-help-companies-patch-software-bugs/ar-AA1WwdjW",
          "published_date": "2026-02-17T14:01:05Z"
        },
        {
          "title": "VulnCheck lands $25m to expand threat intelligence",
          "link": "https://fintech.global/2026/02/18/vulncheck-lands-25m-to-expand-threat-intelligence",
          "published_date": "2026-02-18T10:34:27Z"
        }
      ]
    }
  ]
}

Continue job

To process more records after reviewing the initial results of a job submitted with a limit, use POST /catchAll/continue. It extends the limit without restarting the job — all analysis, validation, and enrichment logic from the original job is preserved. If you submit without a limit, the job processes all available data for the scope and there is nothing to continue.

curl -X POST "https://catchall.newscatcherapi.com/catchAll/continue" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
    "new_limit": 100
  }'

Show Continue job response

{
  "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
  "previous_limit": 10,
  "new_limit": 20,
  "status": "accepted"
}

new_limit must be greater than the limit set in the original job.

List user jobs

GET /catchAll/jobs/user returns all jobs created with your API key, sorted by creation date, most recent first. Supports pagination via page and page_size parameters.

curl "https://catchall.newscatcherapi.com/catchAll/jobs/user" \
  -H "x-api-key: YOUR_API_KEY"

Show List user jobs response

{
  "total": 27,
  "page": 1,
  "page_size": 2,
  "total_pages": 14,
  "jobs": [
    {
      "job_id": "5f0c9087-85cb-4917-b3c7-e5a5eff73a0c",
      "query": "Series B funding rounds for SaaS startups",
      "created_at": "2026-02-24T13:57:56.267572",
      "status": "completed"
    },
    {
      "job_id": "8d618890-f9f5-4c97-af17-236136a306a7",
      "query": "Find corporate headquarters relocations in the US",
      "created_at": "2026-02-18T20:25:20.940731",
      "status": "completed"
    }
  ]
}

Get started

Guides and concepts

How to

API Reference

Libraries

Integrations

Jobs lifecycle

Initialize job

Create job

Get job status

Get job results

Continue job

List user jobs

See also

Get started

Guides and concepts

How to

API Reference

Libraries

Integrations

​Jobs lifecycle

​Initialize job

​Create job

​Get job status

​Get job results

​Continue job

​List user jobs

​See also

Jobs lifecycle

Initialize job

Create job

Get job status

Get job results

Continue job

List user jobs

See also