> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pgw.sipmicro.services/llms.txt
> Use this file to discover all available pages before exploring further.

# Read the push log

> List the push events that pgw recorded, and set how long pgw keeps them.

Use the push log to check whether a device got its call push and what the push service answered. pgw stores each push that it sends, skips, or holds back as a push event in its database.

## List the newest push events

Call the API with your tenant's API key.

```bash theme={null}
curl -s -H "Authorization: Bearer $PGW_API_KEY" "http://127.0.0.1:8080/api/v1/push-events?limit=20"
```

pgw returns the tenant's newest events first, as `{"items": [...]}`. `limit` is from 1 to 1000, and 100 by default. The endpoint has no cursor, so it returns at most the newest `limit` events.

Each event has the following fields.

| Field | Description |
| - | - |
| `id` | The event's ID. |
| `binding_key` | The key of the binding that pgw pushed to. |
| `type` | `call`, `missed`, `refresh`, or `test`. |
| `provider` | `apns`, `fcm`, or `webpush`. |
| `push_type` | The kind of push that pgw sent, such as `voip` or `alert` for APNs, `data` for FCM, or `webpush` for a browser. |
| `status_code` | The push service's HTTP status, or `0` when pgw got no answer. |
| `latency_ms` | Milliseconds from the start of the attempt to its end. |
| `error` | Why the push failed or wasn't sent. Absent when the attempt had no error. |
| `call_id` | The Call-ID of the call that the push is for. Absent for a push without a call. |
| `created_at` | When the attempt ended. |

pgw stores an event within about a second of the push. A push that pgw didn't send because the device reached `call_push_rate_per_binding` has no event. It counts in `pgw_pushes_total` with the result `limited`.

When a call ends while its call push still waits in pgw's queue, pgw drops the push and sends no missed-call push. The log line for the push shows `err="push: call ended"`.

## Set how long pgw keeps push events

pgw keeps push events for `push_event_retention_days` days, 7 by default, and deletes older events every 5 minutes. Set `0` to keep events forever. The largest value is `36500`.

**1. Set the retention**

Set the number of days in the configuration file, or set `PGW_PUSH_EVENT_RETENTION_DAYS`.

```yaml theme={null}
push_event_retention_days: 30
```

**2. Restart pgw**

```bash theme={null}
sudo systemctl restart pgw
```

## Next steps

> [card] [Push lines in the logs](https://docs.pgw.sipmicro.services/logs.md#push-lines)
>
> Find the log line for a push, with the device that it went to.

> [card] [Push metrics](https://docs.pgw.sipmicro.services/metrics.md#pushes)
>
> Watch push results and queue depth across all devices.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.