# List the account's allow and deny lists

`GET /api/v1/ip/lists`

- Authentication: Secret API key as a bearer token
- Billing: Free.
- Group: IP

Every allow and deny list on the account, oldest first, without the entries. A list belongs to the account rather than to whoever created it: every member's lookups apply it and any member may change or remove it. `meta` carries the two limits, how many lists an account may hold and how many entries one list may carry.

The lists apply to every lookup the account is billed for — the API, the dashboard, batches, bulk runs, monitors and the browser widget. Deny lists are checked before allow lists, so a contradiction fails closed. A lookup that hits one carries `account_list` (`{ id, name, kind, entry }`): an allow-list hit answers `risk_score: 0` with a single `allowlisted` signal of weight 0, a deny-list hit adds `denylisted` 100, and `sources` gains `account-lists` with the list's last change as its version.

## Example request

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

## Responses

### 200 — The account's lists.

```json
{
    "success": true,
    "data": {
        "lists": [
            {
                "id": 7,
                "name": "Office egress",
                "kind": "allow",
                "entry_count": 2,
                "created_at": "2026-09-12T09:00:00+00:00",
                "updated_at": "2026-09-12T09:00:00+00:00"
            }
        ]
    },
    "meta": {
        "max_lists": 20,
        "max_entries": 5000
    }
}
```

### 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

---

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