We strongly recommend that before you start using the Cato API, please review the Support Policy for the Cato API.
Overview of eventsFeed
The eventsFeed query helps you analyze events generated by activities related to networking, security, Sockets, Cato Clients, and more. The event data that this query returns is similar to the Monitoring > Events page in the Cato Management Application.
For reseller accounts, you can create separate API keys inside each customer account that you are connecting to the Cato API. For more about rate limiting and the eventsFeed API query, see Understanding Cato API Rate Limiting.
Understanding Fetched Events
The eventsFeed API call is designed for high-volume analysis and monitoring of events in your account. The data for this API query is updated in near real-time.
Cato stores event data for the previous three days. Every 24 hours, data that is older than three days is deleted.
When there are more than 3000 events in the API server queue, the results are paginated. This lets you iteratively fetch events until they reach the end of the queue.
These fields are related to the pagination for the events: marker, and fetchedCount. See below for explanations of these fields.
Enabling eventsFeed for Your Account
Use the API Access Management window to enable your account to send events to the Cato API server. After you enable eventsFeed, wait about 30 minutes for the API server to collect enough events to return data for the query.
To enable eventsFeed for your account:
In the navigation pane, select Administration > API & Integrations and click the Events Integration tab.
Select Enable integration with Cato events. Your account starts sending events to the Cato API server.
Details for the eventsFeed Fields
These are the details that the eventsFeed fields can show for the query:
marker - The marker field is a unique identifier for the last event that the API query returned
fetchedCount - number of events fetched (maximum 3000 events per fetch)
accounts (eventsFeedAccountRecords) - event data for the account (array with nested queries and fields)
eventsFeed Marker
When there are more than 3000 events in the API server queue, the Marker field shows an identifier that indicates the start of a new iteration to fetch events. For example, if the query returns 7500 events, then these are the results over the fetch iterations:
first iteration - fetchedCount = 3000 (events), marker = 1234abc
second iteration - fetchedCount = 3000 (events), marker = 4567def
third iteration - fetchedCount = 1500 (events), marker = 8901xyz
You can ignore the marker value for the final iteration
Markers can point to the events queue for up to the previous three days.
eventsFeed fetchedCount
The fetchedCount field shows the total number of events in the current fetch action. The maximum value for this field is 3000.
eventsFeed Accounts
The Accounts (eventsFeedAccountRecords) fields show the account IDs and event data for this query. Use the eventsFeedAccountsRecords > EventRecord > EventFieldName argument to filter the event data that is displayed for the query. For more about the EventRecords, see Cato API - EventsFeed > EventRecord.
eventsFeed > records > EventFieldName
For more information about the EventFieldName enum values for the different types of events, see the Cato Networks GraphQL API Reference.
Arguments for the eventsFeed
These are the arguments that you can pass and define the data that is returned by the query:
accountIDs - account IDs (for multiple accounts, enter the IDs as an array)
filters (EventFieldFilterInput) - filter the event and audit log data that is queried (array with nested queries)
marker - only show events for a specific fetch iteration according to the marker value
eventsFeed ID Argument
Enter one or more Cato account IDs for the data that the query returns. This argument is mandatory.
This account ID isn't shown in the Cato Management Application, instead it is the number in the URL for the Cato Management Application. For example, the account ID is 26 for the following URL: https://cc2.catonetworks.com/#!/26/topology.
eventsFeed filters Argument
The filters (EventFieldFilterInput) argument lets you define the specific events that are included in the query. These are the arguments you can define:
fieldName > EventFeedFilterFieldName - define the event type or subtype from Event Discovery
operator - define how to activate the values to filter the event data
values - define the filter value that is used with the operator
The following filter syntax is an example of a query that is filtered to show event types with the value Security:
"filters": [
{
"fieldName": "event_type",
"operator": "is",
"values": ["Security"]
}
]The following filter syntax is an example of a query that is filtered to only show event subtypes with the value Internet Firewall:
"filters": [
{
"fieldName": "event_sub_type",
"operator": "is",
"values": ["Internet Firewall"]
}
]eventsFeed marker Argument
The marker argument is mandatory and lets you limit the query to the events for a specific fetch iteration. For example, if the query returns 10500 events, then these are the results over the first three fetch iterations:
first iteration - fetchedCount = 3000 (events), marker = 1234abc
second iteration - fetchedCount = 3000 (events), marker = 4567def
third iteration - fetchedCount = 3000 (events), marker = 8901xyz
To show only the events in the second iteration, set the marker argument to 4567def.
To fetch all the queued events, run the query with an empty marker argument (marker:"") with the initial GraphQL query.