Event Search

This article provides definitions and instructions for searching events within the RiskIQ interface and API, including:

  • Using quick filters
  • Building  queries in the search bar 
  • Saving queries for later use
  • Sorting and pagination
  • Searching and retrieving results via the API

For more information on events, see the related articles: Event Workflow, Event-Types, and Event Submission

Events are notifications within the RiskIQ system that provide information about a particular type of threat. Which event-types you see in your workspace will depend on the RiskIQ products you have purchased and your access permissions as a user. Talk to your RiskIQ Technical Account Manager if you have any questions about the events enabled in your workspace or about user permission controls.

Your events can be viewed in app.riskiq.net by selecting 'Events' from the navigation menu at the top right, or by clicking on any of the graphics in the Events Dashboard.

Event Search in the UI

Events are represented in a list on the left-hand side of the side. Click on a list item to bring up its details in the panel on the right. 

To search your events, you can use either the quick filters on the left-side of the screen for commonly used queries, or click on the search bar at the top to access advanced search options, including additional filters and operators to craft custom queries.

Both the quick filters and advanced search filters are organized by the event-types enabled in your workspace / user login, with attributes that apply across different types in a "Common" section, and then filters that only pertain to each individual event-type in specific sections labeled with the event-type name.

By default, events in the dismissed and resolved statuses are filtered out when you navigate to this screen. You can clear all filters at any point by clicking the 'Reset All' button.

Searching Events Using Quick Filters

You can click to expand a filter to see all its options listed below it along with a preview of the number of event results each option relates to. Clicking on the checkmark next to one of the options creates a filter that includes results with that value, while clicking on the X creates a filter that excludes results with that value. You can include or exclude multiple values within the list of options in a filter. You can keep the filter choices expanded to view the counts as they change, or collapse them to make more screen space for other filters.

As you select quick filters, it automatically populates the search bar for you in the same fashion as if you had typed it yourself or used the query builder to set the query.

All filters are alphabetically listed except for event-type and status (the two most commonly used filters), which are pinned at the top of the Common Quick Filters list.

Example: A query for all Domain Infringement events which are NOT currently in the dismissed or resolved status.

Example: The same query with the filtering options for status and event-type collapsed.

You can also collapse the entire 'Common' section. Note that you can still see that some filters for type and status have been applied at a glance, but you will need to expand the section again or check the search bar at the top to see more details on exactly what kind of filters have been applied on these fields.

Example: Using the Domain Infringement-specific set of event filters to drill down further to see only Domain Infringement events that meet my previous status criteria and also resolve to parked pages.

You can increase the width of the quick filters in order to accommodate the length of long filter values.

Example: Expanding the width of the filters allows longer values like long email addresses to be shown in full.

For filters with a long set of options, you can use the magnifying glass icon to the right of the filter name to search for a specific value. The checkmark at the top also allows you to select all facet choices in the list, and the X when 1 or more selections have been made lets you clear your choices. 

Searching Events Using the Search Bar

Click on the Search Bar to create advanced query logic using AND and OR operations and an expanded set of operators. You may use the query builder to click on operators and populate them in your query, or you can type your query directly. 

Queries are case-sensitive, and event-types and statuses must be capitalized. Help text next to certain search operators provide tips on valid options accepted by that filter.

In the search bar syntax, each logical clause is separated by a pipe character ("|"). Two clauses connected with a pipe represents an AND statement between these two conditions. Phrases in parentheses separated by commas represent OR logic between different option in the same filter. The word "or" can be used between different filters to signify this logic as well. 

In the complex search query below, the query is returning the set of all events matching on 3 conditions:

  1. Status is neither Resolved NOR Dismissed
  2. AND the event-type is Domain Infringement
  3. AND either site parked = Yes, the event was created within the past 2 months, OR it is both parked AND was also created in the past 2 months

Note that the result count is now 50 rather than 19 as seen in the screenshots above since there are still 19 Domain Infringement events which are parked and not in the resolved or dismissed status, but now there are also 31 additional results included in the query which are Domain Infringement events, that are not dismissed or resolved, and are not parked, but were created in the last 2 months. 

The search bar is also where you can conduct a specific search if you already know the value you are looking for. For example, if I wanted to see all domain infringement events registered to a specific registrant email address or to a specific email domain.

Example 2: Filtering for all non-resolved and non-dismissed Domain Infringement events with a Gmail registrant email address.

You can also perform a "simple" search for a string without any specified search operator simply by typing it into the search bar. This will bring up all events that match that exact term in any field.

Example 3: Filtering for all events that match the word "riskIq" in any searchable field.

The system will automatically put quotes around your term for you, however, if your term is a multi-word phrase, put quotes around it before submitting the query to indicate that you want the entire phrase together, as opposed to a match on any of the individual parts of it. This will make your term appear in double quotations after it's submitted.

Example 4: Filtering for all events that match the phrase "RiskIQ, Inc." in any searchable field.

Saving Search Queries

You can also created saved queries in order to quickly access complex, or commonly used queries without having to re-create them each time in the search bar of quick filters by clicking the 'save' button to the right of the search bar.

Saved queries can be selected from a drop-down list on the left-hand side of the Query Builder. Saved queries can be personal to your user login ("My Queries"), or shared with all users in your workspace ("Workspace Queries").

Event Sorting in the UI

You can change the order in which the results of your search appear by changing the sort option. Click on 'Sort' at the top of the events list to bring up a drop-down menu of different sorting choices. The default sort is in descending order by the date of event creation (sorting by newest to oldest).

You can also change the sorting of counts within a single quick filter by using the up/down arrows icon to the right of each filter name. By default, all facet results are sorted in descending order (most results to least), but you can reverse the order or sort alphabetically in ascending or descending order as well.

Pagination of Results

To change the number of events that appear on each page, use the settings icon at the upper right (next to the data export button) to select a high or lower number of results.

For searches that bring up larger numbers of results, you can scroll through pages of events by clicking on the arrows showing the result count at the top of the events list. 

The current sort / pagination settings are reflected in the URL parameters as well. Ex. For the following URL:

  • First number is the page number you are on (1)
  • Second is the total number of pages (68)
  • Third number is the number to show per page (100)
  • Fourth number is the sort ascending/descending (1 for descending, or -1 for ascending)
  • The words at the end reflect which sort is applied (e.g. createdAt in this case)

Searching Events via API

Event searching can also be done via API with a valid API token and password. Ask your RiskIQ Technical Account Manager if you do not have or do not know your API credentials. 

See RiskIQ API Documentation for more details on using the RiskIQ API.

Search Request

Path: /event/search

Method: POST

Requests consist of a repeatable set of filters (each compromised of a field, value, and type), plus optional parameters for results and offset. 

By default, only createdAt is supported as a field option, however, full filtering capabilities via API mirroring those in the UI are available on request. Supported values for type and details on setting the results and offset parameters are listed below. 

example: API search for all events created on or after Jan. 1, 2015 

Request Parameters:

resultsintOptionalDefault: "50"Maximum number of results to return in a result set. Defaults to 50; maximum 2000.
offsetintOptionalDefault:"0"Offset of the first result returned. For example, offset=50 would return a result set starting with the 50th result.

Search Response

The response of your search will contain the offset of your search, the total results in your search, and then each of the event results up to the max allowed by the results parameter in your search request. 

Each event contains the following information:

GET Events by Event ID

You can also search for a single event and retrieve it directly by event ID. In this case, your response would only include that event without an offset or total results value.

Path: /event/{event ID}

Method: GET