Querying for events and superevents

Introduction

This section gives an introduction to searches in GraceDB. Searches can be done from the “Search” and “Latest” pages in the web interface or through the API when using the ligo-gracedb client package. In the web interface, use the dropdown menu to set the search type (superevent or event). When doing a search through the API with the client package, use the events() and superevents() methods to query for events and superevents, respectively.

Queries sometimes have a keyword, which may or may not be required. In general, a query looks like keyword: value. Multiple attributes can be included in a query (ex: key1: val1 key2: val). The sections below show different attributes that can be queried on and the corresponding syntax.

Some information on combining queries is provided at the end.

Event queries

NOTE: clicking the ‘Get neighbors’ checkbox will result in an additional neighbors query for each item in the search results, and the neighbors are thus shown in the results table. However, this causes the overall query to take longer, which is why it is un-checked by default.

By instruments

Order matters, because the instruments are stored in the database as a string. Examples:

  • instruments: "H1,L1,V1"

  • instruments: "V1,L1"

By false alarm rate

  • far < 1e-7

  • far: 3.6823e-4

  • far >= 2e-9

By event attributes

Relational and range queries can be made on selected event attributes. Examples:

  • singleinspiral.mchirp >= 0.5 & singleinspiral.eff_distance in 0.0,55

  • (si.channel = "DMT-STRAIN" | si.channel = "DMT-PAIN") & si.snr < 5

  • mb.snr in 1,3 & mb.central_freq > 1000

Attributes in the common event object (e.g. gpstime, far, instruments) do not need qualifiers. Attributes specific to inspiral or burst events, for example, require qualification. Abbreviations are available: si for singleinspiral, ci for coincinspiral and mb for multiburst. A full mapping of available abbreviations are in the table below:

Event Subclass Query Abbreviations

Event Subclass

Query Abbreviation

coincinspiralevent

ci, coincinspiral

grbevent

grb

lalinferenceburstevent

li

mlyburstevent

ml

multiburstevent

mb, multiburst

siminspiralevent

inj

singleinspiral

si

Note that by a quirk of the query parser, querying for MLyBurstEvent attributes must use the ml abbreviation. In other words, querying for mlyburstevent.detection_statistic > 1.0 will fail, but ml.detection_statistic > 1.0 will succeed.

By GPS time

Specify an exact GPS time, or a range. Integers will be assumed to be GPS times, making the gpstime keyword optional. Examples:

  • 899999000 .. 999999999

  • gpstime: 899999000.0 .. 999999999.9

By creation time

Creation time may be indicated by an exact time or a range. Date/times are in the format 2009-10-20 13:00:00 (must be UTC). If the time is omitted, it is assumed to be 00:00:00. Dates may also consist of certain variants of English-like phrases. The created keyword is optional. Examples:

  • created: 2009-10-08 .. 2009-12-04 16:00:00

  • yesterday..now

  • created: 1 week ago .. now

Warning

Due to a bug in GraceDB, it is recommended that you always include the created keyword, as some queries fail without it.

By graceid

Graceids can be specified either individually, or as a range. The gid keyword is optional. Examples:

  • gid: G2011

  • G2011 .. G3000

  • G2011 G2032 G2033

By label

You may search for events with a particular label or set of labels. The label keyword is optional. Label names can be combined with binary AND: ‘&’ or ‘,’ or binary OR: ‘|’. For N labels, there must be exactly N-1 binary operators (parentheses are not allowed). Additionally, any of the labels in a query string can be negated with ‘~’ or ‘-‘. Examples:

  • label: INJ

  • EM_READY & ADVOK

  • H1OK | L1OK & ~INJ & ~DQV

See Labels in GraceDB for a list of current labels.

By submitter

To specify events from a given submitter, indicate the name of the submitter in double quotes. The submitter keyword is optional. While LIGO user names are predictable, most events are submitted through robot accounts and are not as predictable. This is probably a defect that ought to be remedied. Examples:

  • "waveburst"

  • submitter: "joss.whedon@ligo.org"

By superevent status

Use the in_superevent keyword to specify events which are/are not part of any superevent. Use the superevent keyword to specify events which are part of a specific superevent. Use the is_preferred_event keyword to specify events which are/are not preferred events for any superevent. Examples:

  • in_superevent: True

  • in_superevent: False

  • superevent: S180525c

  • is_preferred_event: True

  • is_preferred_event: False

By run identifier

Events (and superevents) can be queried by Observation/Engineering/Science run identifier, which is based on a preset gpstime range. The runid: keyword is optional. Examples and available options are below:

  • runid: O4

  • O3

  • O1 O2

GraceDB Queryable Run ID’s

runid

gpstime/t_0 range

O4

(1422118818, 1447516818), (1396796418, 1422118818), (1368975618, 1389456018)

O4c

(1422118818, 1447516818)

O4b

(1396796418, 1422118818)

O4a

(1368975618, 1389456018)

ER16

(1394982018, 1396796418)

ER15

(1366556418, 1368975618)

O3

(1238166018, 1269363618)

ER14

(1235750418, 1238166018)

ER13

(1228838418, 1229176818)

O2

(1164556817, 1187733618)

O1

(1126623617, 1136649617)

ER8

(1123858817, 1126623617)

ER7

(1117400416, 1118329216)

ER6

(1102089616, 1102863616)

ER5

(1073822416, 1078876816)

ER4

(1057881616, 1061856016)

ER3

(1044136816, 1045785616)

ER2

(1026666016, 1028480416)

ER1

(1011601640, 1013299215)

ER1test

(1010944815, 1011601640)

S6

(931035296, 971622087)

S6A

(931035296, 935798487)

S6B

(937800015, 947260815)

S6C

(949449543, 961545687)

S6D

(956707143, 971622087)

Superevent queries

Many of the queries for superevents are identical to that of events. Only production superevents are returned by default. See By category for information on specifying Test or MDC superevents.

By id

The keywords id or superevent_id are optional. You can search by a superevent’s S-type ID or its GW ID (if it has one). See Date-based IDs for more information on superevent IDs. Examples:

  • id: S180525a

  • superevent_id: S170817b

  • GW180428C

  • TS181212xz

Superevent ID prefixes and wildcards

Superevent IDs can have the following valid prefixes:

  • S (production superevent)

  • MS (MDC superevent)

  • TS (test superevent)

  • GW (confirmed Gravitational Wave)

You can use a * at the end of a superevent ID prefix to match all superevents that start with that prefix. This enables flexible searches for multiple superevents on a given day or with a common prefix. Only * is supported as a wildcard, and it must appear at the end of the prefix.

Examples:

  • S250908* (matches all superevents for 2025-09-08)

  • S2509* (matches all superevents for September 2025)

  • S25* (matches all superevents for 2025)

  • GW250908* (matches all GW superevents for 2025-09-08)

Invalid queries and error messages:

  • Using an invalid wildcard (e.g., S250908%): Invalid wildcard in query: 'S250908%'. Only '*' is supported as a wildcard.

  • Using an invalid prefix (e.g., XS250908*): Invalid superevent prefix in query: 'XS'. Allowed prefixes are: S, MS, TS, GW.

  • Querying with an event graceid (e.g., G0029): 'G0029' looks like an event graceid. Only superevent IDs (S, MS, TS, GW) are valid in this search.

  • Querying with a completely invalid string (e.g., R001): 'R001' is not a valid superevent ID or query. Valid superevent IDs start with S, MS, TS, or GW followed by a date and optional suffix. Example: S250908a or GW250908A.

By category

Specify a superevent category (Production, Test, or MDC). Only production superevents are returned by default. The keyword category is optional. Examples:

  • Test

  • category: MDC

By GPS time

Same as for event queries, with keywords gpstime or t_0.

By other time attributes

Queries based on the t_start and t_end attributes are also available and require the corresponding keywords. Examples:

  • t_start: 899999000

  • t_end: 899999000.0 .. 900000000.0

By preferred event graceids

Specify an event graceid or range of event graceids with keyword preferred_event to get all superevents with corresponding preferred events. Examples:

  • preferred_event: G123456

  • preferred_event: G123456 .. G123500

By event graceids

Specify a graceid or range of graceids with keyword event to get all superevents which contain the corresponding event(s). Examples:

  • event: G123456

  • event: G123456 .. G123500

By GW status

Query for superevents which are confirmed as GWs or not with the is_gw keyword. Examples:

  • is_gw: True

  • is_gw: False

By creation time

Same as for events.

By submitter

Same as for events.

By label

Same as for events.

By run identifier

Same as for events.

By public status

Use the is_public or is_exposed keywords. Examples:

  • is_public: True

  • is_exposed: True

Or, just add either “public” or “internal” to your query.

By preferred event FAR

Examples:

  • far < 1e-5

  • FAR >= 0.01

  • far in 1e-7, 2.5e-6

Combining queries

Queries can be combined by separating them with a space. This effectively “AND”s them. Do not use binary operators like ‘&’ or ‘|’ except between labels in a label-based query or in a query on selected event attributes (see examples above).