Events API quickstart guide

Transform news into actionable business intelligence with structured events! This guide helps you make your first API calls to retrieve structured event data from news articles.

Before you start

Before you begin, make sure you meet these prerequisites:

An API key (obtain one through our pricing page)
Basic understanding of REST APIs
Your preferred HTTP client (curl, Postman, etc.)
Basic knowledge of JSON data format

Get started

Verify your API access

First, let’s verify that your API key works and the service is available:

curl -X GET https://events.newscatcherapi.xyz/api/health \
  -H "x-api-token: YOUR_API_KEY"

You should receive:

{
  "message": "Healthy"
}

Check your subscription details

Check what event types are available to you:

curl -X GET https://events.newscatcherapi.xyz/api/subscription \
  -H "x-api-token: YOUR_API_KEY"

This shows your subscription status and available events:

{
  "active": true,
  "calls_per_seconds": 5,
  "plan_name": "events",
  "usage_assigned_calls": 10000,
  "usage_remaining_calls": 9959,
  "additional_info": {
    "available_events": ["layoff", "data_breach", "fundraising"]
  }
}

Explore event fields

Before searching, let’s see what fields are available for a specific event type:

curl -X GET "https://events.newscatcherapi.xyz/api/events_info/get_event_fields?event_type=layoff" \
  -H "x-api-token: YOUR_API_KEY"

This returns the fields you can use in your searches:

{
  "message": "Success",
  "count": 12,
  "fields": {
    "company_name": {
      "type": "String",
      "usage_example": {
        "company_name": "String Example"
      }
    },
    "event_date": {
      "type": "Date",
      "usage_example": {
        "event_date": {
          "lte": "now",
          "gte": "now-1d"
        }
      }
    }
    // ... other fields
  }
}

Search for events

Now let’s perform your first event search:

curl -X POST https://events.newscatcherapi.xyz/api/events_search \
  -H "x-api-token: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "layoff",
    "attach_articles_data": true,
    "additional_filters": {
        "extraction_date": {
            "gte": "now-1d",
            "lte": "now"
        },
        "layoff.number_of_people_laid_off": {
            "gte": 10000
        }
    }
}'

This searches for recent large layoff events, with over 10,000 people affected, from the last 24 hours. The response will include structured event data and associated articles.

{
  "message": "Success",
  "count": 2,
  "events": [
    {
      "id": "n1jk-pQBvyT_ytpRpzBn",
      "layoff": {
        "summary": "The Trump administration is planning large-scale layoffs in the federal workforce, with over 65,000 employees accepting a deferred resignation offer. The layoffs are part of the 'Department of Government Efficiency' Workforce Optimization Initiative, which aims to reduce the federal workforce by 5% to 10%.",
        "layoff_reason": "Workforce optimization initiative",
        "max_number_of_people_laid_off": 65000,
        "how_much_related": "Excellent",
        "is_relevant_for_real_estate": false,
        "location": [
          {
            "country": "United States",
            "city": "Washington",
            "raw_location": "Washington, DC",
            "county": "District of Columbia",
            "state": "Washington"
          }
        ],
        "number_of_people_laid_off": 65000,
        "percentage_of_people_laid_off": 5,
        "min_number_of_people_laid_off": 65000
      },
      "event_type": "layoff",
      "global_event_type": "Layoff",
      "associated_article_ids": ["94496b567dbd387718ab8065dea16c1d"],
      "extraction_date": "2025-02-12 16:01:16",
      "event_date": "2021-10-15 00:00:00",
      "company_name": "Department of Government Efficiency",
      "articles": [
        {
          "link": "https://www.cnn.com/2025/02/12/politics/federal-employees-layoffs-trump/index.html",
          "id": "94496b567dbd387718ab8065dea16c1d",
          "title": "DOGE's power expands as federal agencies start planning large-scale layoffs"
        }
      ]
    },
    {
      "id": "lFjQ9pQBvyT_ytpR2yrN",
      "layoff": {
        "summary": "Meta conducted layoffs on October 10, 2022, affecting 11,000 employees, which is 11% of the company's workforce. The layoffs were a surprise to many employees, including those with strong performance records.",
        "layoff_reason": "To eliminate underperformers",
        "max_number_of_people_laid_off": 11000,
        "how_much_related": "Excellent",
        "is_relevant_for_real_estate": false,
        "location": [
          {
            "country": "United States",
            "city": "Menlo Park",
            "raw_location": "Menlo Park, San Mateo, California, United States",
            "county": "San Mateo",
            "state": "California"
          }
        ],
        "number_of_people_laid_off": 11000,
        "percentage_of_people_laid_off": 11,
        "min_number_of_people_laid_off": 11000
      },
      "event_type": "layoff",
      "global_event_type": "Layoff",
      "associated_article_ids": ["79f95268b0415c681ecb961f3e371742"],
      "extraction_date": "2025-02-11 21:01:10",
      "event_date": "2022-10-10 00:00:00",
      "company_name": "Meta",
      "articles": [
        {
          "link": "https://digg.com/insider/link/meta-job-cuts-surprise-some-employees-strong-performers",
          "id": "79f95268b0415c681ecb961f3e371742",
          "title": "Meta's Job Cuts Surprised Some Employees Who Said They Weren't Low Performers"
        }
      ]
    }
  ]
}

What’s next

Now that you’ve made your first API calls, you can:

Learn about Event types
Explore API reference
Set up event monitoring for your specific use case

Need help? Contact our support team at support@newscatcherapi.com

Overview

How to

Event types

Endpoints

Events API quickstart guide

Before you start

Get started

What’s next

Overview

How to

Event types

Endpoints

​Before you start

​Get started

​What’s next

Before you start

Get started

What’s next