---
title: "List Alerts"
method: GET
path: "/v1/alerts"
tags: ["v1"]
---

# List Alerts

`GET /v1/alerts`

## Request

- Base URL: `https://api.ellipsis.dev`
- URL: `https://api.ellipsis.dev/v1/alerts`
- Auth: HTTP bearer

List budget alerts for the organization, newest first.

Optionally filtered by status and source.

Available to all credential types, so an agent can check "is
this org near budget?" mid-task.

## Query parameters

- `status` 'open' | 'dismissed' | 'expired': The alert's lifecycle state: open until a human dismisses it or the system resolves it (the condition cleared or the alert went stale).
- `source` 'budget': What raised the alert.
- `limit` integer
- `cursor` string, nullable

## Headers

- `user-agent` string, nullable

## Response `200`

Successful Response

- AlertsListResponse: A page of alerts for the caller's organization.
  - `alerts` Alert[], required: The matching alerts.
    - `body` string, required: The alert body, in Markdown.
    - `created_at` string, date-time, required: When the alert was raised.
    - `cta_label` string, required: The label for the call-to-action link.
    - `cta_url` string, required: Where this alert sends the reader.
    - `id` string, required: The alert's unique identifier.
    - `resolved_at` string, date-time, nullable: When the alert was resolved.
    - `resolved_by` integer, nullable: The GitHub account id of the person who dismissed the alert, when a human resolved it.
    - `severity` 'info' | 'warning', required: Cosmetic only (badge tone, Slack emoji, email subject prefix). Routing is decided by the category, never by severity.
    - `source` 'budget', required: What raised the alert.
    - `status` 'open' | 'dismissed' | 'expired', required: The alert's lifecycle state: open until a human dismisses it or the system resolves it (the condition cleared or the alert went stale).
    - `title` string, required: A one-line, plain-text title.
    - `updated_at` string, date-time, required: When the alert last changed.
  - `has_more` boolean: Whether more results exist past this page.
  - `next_cursor` string, nullable: Pass as `cursor` to fetch the next page. Null on the last page. Opaque — echo it back rather than parsing it.

## Other responses

- `401`: The bearer token is missing, invalid, or revoked.
- `403`: The credential may not perform this action, or the account is blocked.
- `422`: Validation Error

---

[API](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api.md) - [All operations](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/ellipsis/apis/ellipsis-rest-api/revisions/344b16df9a1a?raw)