Event Tracer API

Event Tracer API Endpoints¶

This section documents new API endpoints for tracing FRB events and their associated baseband callback requests.

Querying Baseband Callbacks¶

To retrieve events that should have triggered a baseband request within a specific time window, use the /v1/event-tracer/baseband-callbacks endpoint.

Endpoint: GET /frb-master/v1/event-tracer/baseband-callbacks

Query Parameters: - start_time_utc: Start time in UTC (e.g., 2026-03-11) - end_time_utc: End time in UTC (e.g., 2026-03-18)

Example Usage:

Python

import chime_frb_api
import requests

# Assuming FRBMaster is initialized and authorized
master = chime_frb_api.frb_master.FRBMaster()
master.API.authorize()
headers = {"AUTHORIZATION": master.API.access_token}

url = 'https://frb.chimenet.ca/frb-master/v1/event-tracer/baseband-callbacks?start_time_utc=2026-03-11&end_time_utc=2026-03-18'
r = requests.get(url, headers=headers)
events = r.json()

# Example output for an event
# events[0]
# {
#  'event_no': 1154677896,
#  'snr': 42.34481430053711,
#  'known_source_name': 'B0329+54',
#  'trace': {
#   'event_no': 1154677896,
#   'stages/tsar_classification': 'incomplete',
#   'stages/baseband_callback_request/sites/chime': 'complete',
#   'stages/baseband_conversion/sites/chime': 'complete',
#   'stages/data_registration/sites/chime': 'complete',
#   'stages/data_replication_to_minoc/sites/chime': 'complete',
#   'stages/baseband_callback_request/sites/kko': 'incomplete',
#   'stages/baseband_conversion/sites/kko': 'incomplete',
#   'stages/data_registration/sites/kko': 'complete',
#   'stages/data_replication_to_minoc/sites/kko': 'complete',
#   'stages/baseband_callback_request/sites/gbo': 'incomplete',
#   'stages/baseband_conversion/sites/gbo': 'incomplete',
#   'stages/data_registration/sites/gbo': 'complete',
#   'stages/data_replication_to_minoc/sites/gbo': 'complete',
#   'stages/baseband_callback_request/sites/hco': 'incomplete',
#   'stages/baseband_conversion/sites/hco': 'incomplete',
#   'stages/data_registration/sites/hco': 'complete',
#   'stages/data_replication_to_minoc/sites/hco': 'complete',
#   'update_timestamp': 1773388272.0920215
#  }
# }

Response Details:

The endpoint returns a list of events. Each event object includes:

event_no (integer): The event number.
snr (float): Signal-to-noise ratio.
known_source_name (string): Name of the known source, or a real-time pipeline categorization (e.g., EXT, AMB, GAL) if unknown.
trace (object, optional): A dictionary containing trace information for the event.
- event_no (integer): The event number.
- stages/tsar_classification (string): Status of TSAR classification.
- stages/baseband_callback_request/sites/{SITE} (string): Status of baseband callback request for a specific site (e.g., 'chime', 'kko', 'gbo', 'hco'). Value is 'complete' or 'incomplete'.
- stages/baseband_conversion/sites/{SITE} (string): Status of baseband conversion for a specific site.
- stages/data_registration/sites/{SITE} (string): Status of data registration for a specific site.
- stages/data_replication_to_minoc/sites/{SITE} (string): Status of data replication to minoc for a specific site.
- update_timestamp (float): Timestamp of the last update for the trace.

Retrieving Detailed Event Status¶

For more comprehensive information about a specific event, including trace, nearby heartbeats, datatrail info, TSAR classification, and Action rules, use the /v1/event-tracer/event-status/{event_no} endpoint.

Endpoint: GET /frb-master/v1/event-tracer/event-status/{event_no}

Path Parameter: - event_no: The event number (e.g., 1154677896)

Example Usage:

Python

# ... (assuming master and headers are already defined)

event_no = 1154677896
url = f'https://frb.chimenet.ca/frb-master/v1/event-tracer/event-status/{event_no}'
r = requests.get(url, headers=headers)
event_status = r.json()

Note: This is a slow query as it parses multiple databases, including datatrail, to compile the information. The output is verbose and provides detailed insights used to populate the event status page. Note that this is an expensive query and returns a large payload so we can only do this for one event at a time. It can take about a minute to run so be patient.

Response Schema for `event-status`¶

The response is a JSON object with the following top-level keys:

actions (object): Details about requested and received actions for different data types (intensity, baseband, site-specific baseband).
- want (object): Actions that were requested.
- got (object): Actions that were successfully completed.
tsar_classification (string): Classification from TSAR.
datatrail (object): Information about data registration and replication across different storage elements.
- intensity (object): Details for intensity data.
  - registered (boolean): Whether the data is registered.
  - should_be_at_minoc (boolean): Whether the data should be at minoc.
  - larger_dataset (object): Dataset metadata including name, scope, preferred storage elements, and deletion policy.
  - data_path (string): Path to the data.
  - num_files (integer): Number of files.
  - missing_files (array): List of missing files.
- baseband, kko_baseband, gbo_baseband, hco_baseband (objects): Similar structure to intensity for different baseband data.
trace (object): Same trace information as returned by the baseband-callbacks endpoint, detailing stage completion statuses.
heartbeats (array of objects): A list of heartbeat records, each containing:
- heartbeat_id (integer): Unique ID for the heartbeat.
- site (string): The site (e.g., 'chime', 'kko').
- sent (object): Details about the sent heartbeat, including trigger_time and error.
- received (object): Details about the received heartbeat, including total_data_files, dir_size_gb, finished_time, and heartbeat_sent_unix_s.
event_no (integer): The event number.
update_timestamp (float): Timestamp of the last update.

Important Considerations¶

This tooling is new and may be prone to bugs.
It is recommended to validate events against manual checks to ensure accuracy, especially during the initial weeks of use.