# List this key's saved alerts

listAlerts · GET /api/alerts

## Endpoint
`GET /api/alerts`

Saved alerts belong to the API key that created them. Starter holds 3, Pro 10, Scale 25 (x-api-tiers alerts). After every collection run each alert receives the new and revised documents that match it, by email to the key's own address or by a signed webhook.

## Authentication
```json
[]
```
An empty security requirement means this operation does not declare authentication. Read operation notes for entitlement and protocol-method requirements.

## Parameters
No parameters declared by the specification.

## Responses and errors
| HTTP status | Meaning |
| --- | --- |
| 200 | The alerts and the allowance. |
| 401 | Unknown, revoked or malformed key (code unauthorized). |
| 402 | Not a paid key, or the plan holds no more alerts (code plan_required). |
| 429 | Rate limit exceeded; honour Retry-After. |
| 503 | Alerts are not yet enabled on this deployment (migration 048 pending). |

## Response examples
No response example is supplied by OpenAPI for this operation. The complete response schemas are preserved below; use an actual response for observed values.

## Retry guidance
See [errors and retries](/docs/api/overview#errors-and-retries). Honor operation-specific response headers. A POST may create state; do not replay it automatically.

## Complete operation contract
The expanded contract below includes all parameter constraints, response headers, schemas and examples from OpenAPI.

```json
{
  "path": "/api/alerts",
  "method": "GET",
  "parameters": [],
  "operationId": "listAlerts",
  "summary": "List this key's saved alerts",
  "description": "Saved alerts belong to the API key that created them. Starter holds 3, Pro 10, Scale 25 (x-api-tiers alerts). After every collection run each alert receives the new and revised documents that match it, by email to the key's own address or by a signed webhook.",
  "tags": [
    "keys",
    "Retrieve changes",
    "Manage access"
  ],
  "responses": {
    "200": {
      "description": "The alerts and the allowance.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "alerts",
              "limit",
              "used"
            ],
            "properties": {
              "alerts": {
                "type": "array",
                "items": {
                  "type": "object",
                  "required": [
                    "id",
                    "channel",
                    "target",
                    "active"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "format": "uuid"
                    },
                    "label": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "watch": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "A watchlist slug (list_watchlists)."
                    },
                    "q": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "source": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "channel": {
                      "type": "string",
                      "enum": [
                        "email",
                        "webhook"
                      ]
                    },
                    "target": {
                      "type": "string",
                      "description": "The key's own email, or the https webhook URL."
                    },
                    "active": {
                      "type": "boolean"
                    },
                    "last_delivered_at": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "format": "date-time"
                    },
                    "last_error": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "created_at": {
                      "type": "string",
                      "format": "date-time"
                    }
                  }
                }
              },
              "limit": {
                "type": "integer"
              },
              "used": {
                "type": "integer"
              }
            }
          }
        }
      }
    },
    "401": {
      "description": "Unknown, revoked or malformed key (code unauthorized)."
    },
    "402": {
      "description": "Not a paid key, or the plan holds no more alerts (code plan_required)."
    },
    "429": {
      "description": "Rate limit exceeded; honour Retry-After."
    },
    "503": {
      "description": "Alerts are not yet enabled on this deployment (migration 048 pending)."
    }
  },
  "x-codeSamples": [
    {
      "lang": "curl",
      "label": "curl",
      "source": "curl -s -H \"Authorization: Bearer $CS_API_KEY\" 'https://china-snapshot.com/api/alerts'"
    }
  ]
}
```