# List business monitors

`GET /api/v1/entity/monitors`

- Authentication: Secret API key as a bearer token
- Billing: Free. Listing monitors costs nothing; only their runs are billed.
- Group: Entity

Every saved list of business identifiers on the account, newest first, 100 to a page. Each carries the summary of its last run, including `stopped_reason` when it did not finish cleanly: `insufficient_credits` or `key_spend_cap` where the run stopped part-way, `run_failed` where it died outright, and `run_failed_retrying` where it died and the schedule has been pulled in to check again — `retry_at` in the same block says when that becomes due, and the hourly sweep picks it up at or after that, so between 45 minutes and about an hour and three quarters later. A summary carrying a `stopped_reason` of either failure kind has NO counts in it at all: the run produced none, so read a missing count as unknown rather than as zero.

`meta.retention_days` says how long a list nobody runs is kept. A monitor in active use is never pruned — each run advances `last_run_at` — but one that has stopped being run is deleted along with the identifiers it stored, because an identifier can belong to a sole trader as easily as to a company and nothing in it says which.

## Example request

```bash
curl https://spaw.co/api/v1/entity/monitors \
  -H "Authorization: Bearer sk_live_…"
```

## Responses

### 200 — The account's business monitors.

### 401 — The key is missing, malformed, or revoked.

```json
{
    "success": false,
    "error": {
        "code": "UNAUTHENTICATED",
        "message": "Provide a valid API key as a bearer token.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

### 429 — Over 5 requests per second for the key. Retry after the limit resets.

```json
{
    "success": false,
    "error": {
        "code": "RATE_LIMITED",
        "message": "Too many requests. Retry after the limit resets.",
        "request_id": "req_01m1kgdm4xngzmbmff68g94w0c"
    }
}
```

## Error codes

- `UNAUTHENTICATED` — https://spaw.co/docs/errors/UNAUTHENTICATED
- `RATE_LIMITED` — https://spaw.co/docs/errors/RATE_LIMITED
- `KEY_SCOPE_DENIED` — https://spaw.co/docs/errors/KEY_SCOPE_DENIED
- `EMAIL_NOT_VERIFIED` — https://spaw.co/docs/errors/EMAIL_NOT_VERIFIED

---

Canonical page: https://spaw.co/docs/api/list-entity-monitors · OpenAPI document: https://spaw.co/openapi.json · All endpoints: https://spaw.co/docs/api