---
title: "Events & tracking"
description: "Read event timelines and expose public-safe tracking status."
---

# Events & tracking

Events are chronological status changes for a delivery. Use the authenticated event endpoint for internal timelines and the public tracking endpoint for customer-facing status.

## Authenticated events

```http
GET /v1/deliveries/{delivery_id}/events
```

```bash
curl https://entrega.ao/v1/deliveries/$DELIVERY_ID/events \
  -H "Authorization: Bearer $ENTREGA_SECRET_KEY"
```

```json
{
  "data": [
    {
      "id": "evt_123",
      "event_type": "delivery.created",
      "occurred_at": "2026-04-29T17:30:00Z",
      "source": "system",
      "payload": {"status": "pending"}
    }
  ]
}
```

## Public tracking

```http
GET /v1/deliveries/{delivery_id}/tracking
```

No authentication is required. The response contains only public-safe fields.

```json
{
  "reference": "DLV-2026-00042",
  "status": "in_transit",
  "events": [
    {"event_type": "delivery.created", "occurred_at": "2026-04-29T17:30:00Z"},
    {"event_type": "delivery.in_transit", "occurred_at": "2026-04-29T18:10:00Z"}
  ]
}
```

## Status values

| Status | Meaning |
| --- | --- |
| `awaiting_payment` | Delivery is waiting for payment confirmation. |
| `pending` | Delivery is created and waiting for courier dispatch. |
| `assigned` | Courier accepted or was assigned. |
| `pickup_ready` | Pickup is scheduled or ready. |
| `in_transit` | Courier has picked up and is moving. |
| `out_for_delivery` | Courier is close to final delivery. |
| `delivered` | Delivery completed. |
| `cancelled` | Delivery was cancelled. |
| `failed` | Delivery failed. |
| `stalled` | Delivery needs operational recovery. |