Astro-COLIBRI posts every alert of its important stream to the AT Protocol, the open network behind Bluesky. Anyone can follow it live, for free and without an Astro-COLIBRI account, with any AT Protocol tool, for example the nebra Python package of the Astrosky ecosystem.
The alerts come from the account
@astro-colibri.science
(DID did:plc:v7yqjnko6psoy25novsrlrh6), a few seconds after the
same alert went out on the Kafka alert broker.
Each important alert, and each important update of an event, becomes two records that share the same record key, so the two can be paired:
| Collection | Content | Same as Kafka topic |
|---|---|---|
| science.astro-colibri.alert.ac | The alert in Astro-COLIBRI's native JSON format, the fields /get_event returns | astrocolibri.important.JSON |
| science.astro-colibri.alert.vo2 | The VOEvent 2.0 document converted to JSON, the format of /voevent?json=1 | astrocolibri.important.VOEvent |
Records are never edited or deleted: an update of an event is a new record
pair, with the same astroColibriID as the earlier ones. Unlike
the Kafka topics, which keep alerts for 24 hours, the records stay on the
account permanently.
The archive of everything posted can be browsed in any web browser on atproto.at: ac records and vo2 records (also on pdsls.dev: ac, vo2). To read it from code, see Past alerts.
Install nebra (Python 3.11 or newer):
This prints every new alert as it is posted, with the event's position:
record["data"] is the full alert, with the same fields as the
astrocolibri.important.JSON Kafka topic and the REST API, so
code written for those works on it unchanged. For the VOEvent version,
subscribe to science.astro-colibri.alert.vo2, or to both with
science.astro-colibri.alert.*; message["collection"]
then tells them apart and message["rkey"] pairs them.
nebra.stream starts at the live edge. To catch up after a
break, pass cursor= a Unix time in microseconds: the public
stream replays from that moment, as far back as it keeps recent events (a
limited window). For anything older, read the account directly, see
Past alerts.
From the command line, without writing code (with uv installed, nothing needs to be installed at all), every message is printed as it arrives:
On the AT Protocol anyone can create records under any collection name,
including science.astro-colibri.alert.*. Always filter on the
author: the DID did:plc:v7yqjnko6psoy25novsrlrh6 (as in the
example above, with dids= and the check in the handler) or the
handle astro-colibri.science. The DID never changes, which makes
it the safer of the two.
Both collections share these fields. Their schemas (lexicons) are published on the account as schema definitions (on atproto.at), and can be read as documentation on lexicon.garden (vo2).
| Field | Content |
|---|---|
| alertType | Event type, e.g. grb, gw, neutrino, frb, ot_sn |
| observatory | Discovery observatory or experiment |
| instrument | Instrument, when known (otherwise absent) |
| broker | Broker or service that reported the event, e.g. GCN, TNS, FINK; empty when unspecified |
| triggerID | Trigger identifier (trigger_id in the alert) |
| astroColibriID | Astro-COLIBRI's identifier of the event, the same across all its updates. astro_colibri_id in the alert |
| important | Always true: only the important stream is posted at the moment |
| createdAt | When Astro-COLIBRI published the alert (UTC), not when the event happened |
| data | The alert itself, see below |
Numbers in ac records. The AT Protocol has no
floating-point numbers, so each decimal number in data is
written as a string between № signs, for example
"№182.6365№". This is nebra's convention, and nebra
converts them back for you. With any other client, convert them yourself:
vo2 records hold the VOEvent document exactly
as the Kafka VOEvent topic carries it, converted with
xmltodict.parse(xml, attr_prefix=""): the root key is
voe:VOEvent, XML attributes become plain keys, and every value
is a string, as in the XML. Parameter names and groups are described in the
API documentation.
To look through earlier alerts, open the archive on atproto.at (ac, vo2). To process them in code, list every record ever posted from the account's server, newest first and 100 at a time, without any account:
Each answer ends with a cursor; pass it back as
&cursor=... for the next, older page. In Python:
The server address belongs to the account's hosting and may change. The
current one is always listed in the account's
DID document
(the #atproto_pds service). Records listed this way still carry
the №-encoded numbers.
For a search by position, time or type over the whole history, the REST API is the better tool.
| AT Protocol | Kafka alert broker | |
|---|---|---|
| Alerts | Important stream | All alerts, and the important stream |
| Formats | Native JSON (ac), VOEvent as JSON (vo2) | Native JSON, VOEvent XML |
| Access | Public, no account | Free credentials after accepting the terms of use |
| Timing | Seconds after Kafka | As soon as Astro-COLIBRI publishes |
| Delivery | Best effort; catch up with a stream cursor (recent events) or the record listing | At least once; your read position is kept by the broker |
| History | All records stay on the account | 24 hours |
| Filtering | In your own code | Astro-COLIBRI filters in the SDK |
Whether the AT Protocol mirror is running, and how far behind Kafka it is, is shown live in the broker status panel.
The alerts are public, but not free of conditions: data from Astro-COLIBRI may be used for non-commercial purposes only, including personal, educational, public-research, charitable and governmental use, as set out in the Astro-COLIBRI terms of use. Notices and terms of the original data providers continue to apply.
