How to filter news by event type#

To return only articles about a specific kind of event, add the event.type parameter to your /v1/news/everything request with an event code such as event.type=layoffs. APITube detects the main event in each article and returns only the articles whose event matches. You can pass up to five event types separated by commas, and an article is returned if it matches any of them (OR logic).

curl "https://api.apitube.io/v1/news/everything?event.type=layoffs&api_key=YOUR_API_KEY"

You can send the key as a header (X-API-Key: YOUR_API_KEY) instead of the api_key query parameter. If you omit event.type, no event filter is applied and articles about every kind of event (and none) are returned.

What event types can I filter by?#

Event types are grouped into three categories: business, society and environment. Business covers events like merger-acquisition, ipo, layoffs, bankruptcy, funding-round, earnings, lawsuit, data-breach and recall. Society covers election, protest, crime, terrorism, accident, scandal and conflict. Environment covers earthquake, hurricane, flood, wildfire, drought and volcanic-eruption. Codes are lower-case and hyphenated.

A code that is not on the list returns HTTP 400 with error ER0502, and the message names the invalid value and points you to the event-types endpoint. An empty event.type returns ER0501. To filter by an event without naming each code, use event.category with business, society or environment — an unknown category returns ER0503:

curl "https://api.apitube.io/v1/news/everything?event.category=business&api_key=YOUR_API_KEY"

event.category=business is shorthand for every business event type at once, so it returns articles about mergers, IPOs, layoffs, earnings and the rest in one request.

How to filter by one or more event types#

Pass a single code to read one event type, or a comma-separated list to combine several. This request pulls articles about either of two business events in one call:

curl "https://api.apitube.io/v1/news/everything?event.type=merger-acquisition,ipo&sort.by=published_at&sort.order=desc&api_key=YOUR_API_KEY"

The maximum is five event types per request; extra values beyond the fifth are dropped. Event filtering is part of the shared filter chain, so it combines with any other filter — language, date range, source or entity:

curl "https://api.apitube.io/v1/news/everything?event.type=data-breach&language.code=en&api_key=YOUR_API_KEY"

How to exclude an event type#

To return everything except a kind of event, use ignore.event.type. It follows the same rules — comma-separated, up to five codes, validated against the same list (an invalid code returns ER0504). This keeps broad coverage while dropping earnings stories:

curl "https://api.apitube.io/v1/news/everything?ignore.event.type=earnings&api_key=YOUR_API_KEY"

You can pass event.type (or event.category) and ignore.event.type in the same request to include one kind of event while excluding another.

How do I get the full list of event types?#

Call the GET /v1/news/event-types endpoint to fetch every valid event.type value together with its category, so you never have to guess a code:

curl "https://api.apitube.io/v1/news/event-types?api_key=YOUR_API_KEY"

The response is a JSON object with a status, a categories array (business, society, environment) and an event_types array where each item carries a code and the category it belongs to:

{
    "status": "ok",
    "categories": ["business", "society", "environment"],
    "event_types": [
        { "code": "merger-acquisition", "category": "business" },
        { "code": "ipo", "category": "business" }
    ]
}

Take a code from the list and drop it straight into event.type. The same catalogue is documented in the APITube event types reference.

Common Questions#

• How many event types can I filter by at once?
• What is the difference between event.type and event.category?
• What error do I get for an unknown event type?
• How do I get the full list of event types?

How many event types can I filter by at once?#

Up to five per parameter. event.type and ignore.event.type each accept a comma-separated list, and only the first five values are applied — anything beyond the fifth is dropped. Multiple types in one parameter use OR logic, so an article matches if its detected event is any of them.

What is the difference between event.type and event.category?#

event.type targets one specific event code such as ipo or wildfire. event.category targets a whole group — business, society or environment — and matches every event type inside it. Use event.type when you want precise events, and event.category when you want a broad sweep of a domain. They can be combined with each other and with breaking-news filtering in the same request.

What error do I get for an unknown event type?#

An event code that APITube does not recognise returns HTTP 400 with error ER0502 for event.type (the message lists the invalid code and points you to /v1/news/event-types), or ER0504 for ignore.event.type. An empty event.type returns ER0501, and an unknown event.category returns ER0503. Fetch the valid codes from GET /v1/news/event-types before filtering to avoid these errors.