---
title: "The project-wide routing grid"
method: GET
path: "/api/v1/routes"
tags: ["Events"]
---

# The project-wide routing grid

`GET /api/v1/routes`

## Request

- Base URL: `https://app.lastping.dev`
- URL: `https://app.lastping.dev/api/v1/routes`
- Auth: API key in header `X-Api-Key`

Returns one row per (check, event_type) pair that has ever been
routed — the same rows `GET /api/v1/checks/{id}/routes` would return
for each check individually, gathered project-wide in one call so a
caller does not have to walk every monitor to render a routing
matrix.

Ordered by check name, then event type, for a stable grid.
**Not paginated** — the row count is bounded by monitors × event
types (at most 8 event types per check today), not by unbounded
user activity, so a single response is always the complete answer.

This endpoint is **read-only**. Edit a route through the existing
`PUT`/`DELETE /api/v1/checks/{id}/routes/{event_type}`.

**Console stability note.** This response is shaped by a console screen:
the fields are the ones that screen draws, in the grouping it draws them
in. It stays published because reading it is a reasonable thing to
automate, and no field will be removed or change meaning without a
version. Fields may be ADDED as the screen grows, so treat unknown keys
as normal rather than as an error.

## Response `200`

The full routing grid (may be empty).

- RouteList: The body of `GET /api/v1/routes` — the complete, unpaged routing grid.
  - `routes` RouteRow[], required
    - `check_id` string, uuid, required
    - `check_name` string, required: Third-party text: render it as text, never interpret it as markup.
    - `event_type` 'down' | 'recovery' | 'fail' | 'every-run' | 'success' | 'started' | 'blocked' | 'note', required
    - `channel_ids` string[], required: Always an array (never null), possibly empty.

## Other responses

- `401`: Missing or invalid API key.
- `429`: Too many requests. The per-principal fixed-window rate limit has been exceeded. Retry after the number of seconds indicated by the `Retry-After` response header. The problem body's `code` is `RATE_LIMITED`. It names this limiter specifically, so a client can tell it apart from the application-level throttles that also answer 429 with their own codes and their own, much longer, `Retry-After` values (`TEST_PING_RATE_LIMITED`, `TOO_MANY_ATTEMPTS`). Back off globally on `RATE_LIMITED`; back off on the one operation for the others. The principal is the API key for a key-authenticated request and the USER for a browser session, so every tab one person has open shares one budget.

---

[API](https://skmtc.dev/lastping/apis/lastping-management-api.md) · [All operations](https://skmtc.dev/lastping/apis/lastping-management-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lastping/apis/lastping-management-api/revisions/bbc6eda91c46?raw)