Python SDK

Install

pip install traffic-lights-events

On PyPI as traffic-lights-events. The distribution is traffic-lights-events; the module you import is traffic_lights_events.

Configure

export TL_API_BASE_URL="https://api.traffic-lights.io"
export TL_API_KEY="<your API key>"

Both are required. With either missing, the SDK raises and names what is missing rather than sending nowhere.

Send an event

from traffic_lights_events import emit_event

emit_event(
    "sai.tl.billing",                  # source — who is reporting
    "FLOW_CALLBACK",                   # detail type — what happened
    {"runID": "run-2026-09-28-001",    # detail — must carry runID
     "taskID": "20006510",
     "status": "SUCCESS"},
)

emit_event returns when the event has been accepted and raises if it was not. A timestamp is added to the detail if you do not supply one.

Handle errors

from traffic_lights_events import EmitError, EmitRefused

try:
    emit_event("sai.tl.billing", "FLOW_CALLBACK", detail)
except EmitRefused as exc:
    # Traffic Lights understood the event and refused it.
    # Retrying cannot help — the message carries the server's reason.
    log.error("refused: %s", exc)
except EmitError as exc:
    # Delivery failed — timeout, 5xx, DNS. Retrying may work.
    retry_later(detail)

• Catch EmitRefused before EmitError: a refusal is also an EmitError.
• Keep the two apart. A refusal retried forever never drains; a delivery failure treated as a refusal is an event silently lost.
• Missing runID or a malformed event is refused before any request is made.