:::endpoint GET /v1/admin/fraud/flags

Every fraud flag of the firm, the way the Review queue on the website lists
them: the flags a detector raised about who is behind an account, and the
flags trading rules send here. Where the website reads a value it does not
know as the default, because its addresses get bookmarked, this refuses it: a
client that thinks it filtered and got everything shows the wrong list.

One flag, with its evidence and its people, is [a fraud flag](/docs/api/admin/fraud-flag).
How many flags each view holds is the [summary](/docs/api/admin/fraud-summary).

Needs a firm. Our own staff name one with the `Propper-Workspace` header.

## Request

| Parameter        | Description |
| ---------------- | ----------- |
| `view`           | `open` (the default: still active and above Monitor, what somebody is asked to decide), `monitor` (still active, written by a detector on Monitor without asking anybody), `closed` (resolved, dismissed or cleared by the AI), or `all` |
| `category`       | `ip`, `geo`, `device`, `linking`, `affiliate`, `trading`, or `all` (the default) |
| `level`          | `flag`, `restrict`, `block`, or `all` (the default). The level the flag was raised at |
| `restricted`     | `true` for only the flags that take something away from somebody right now. `false` is the default |
| `q`              | Search, up to 80 characters: the trader's name or email, a name in a group flag, the address, the detector's key, or a whole flag id |
| `sort`           | `-score` (the default, except in `closed`: still active first, then the highest score, then the newest), `-created_at` newest first, `created_at` oldest first, or `-reviewed_at` (the default in `closed`: decided last first) |
| `limit`          | How many, see [pagination](/docs/api/pagination) |
| `starting_after` | The `next_cursor` of the page before. A cursor only works with the `sort` it was handed out with |

```bash
curl "https://api.proppertrading.com/v1/admin/fraud/flags?limit=2" \
  -H "Authorization: Bearer ptat_9f2c1a44_3b8e7d2f5c9a1b4e6d8f0a2c4e6b8d1f" \
  -H "Propper-Workspace: acme"
```

## Response

{
    "data": [
        {
            "object": "fraud_flag",
            "id": "fflag_uq7dx7cy98mz6x93",
            "detector": "shared_device",
            "category": "device",
            "label": "Shared device",
            "score": 91,
            "severity": "critical",
            "level": "block",
            "status": "open",
            "subject": "Jonas Romero",
            "others": 0,
            "ip": null,
            "restricted": false,
            "created_at": "2026-10-01T10:52:29+00:00",
            "reviewed_at": null,
            "action_url": "/admin/fraud?flag=fflag_uq7dx7cy98mz6x93"
        },
        {
            "object": "fraud_flag",
            "id": "fflag_83p7w2fqfhevbgfg",
            "detector": "tor",
            "category": "ip",
            "label": "Tor",
            "score": 90,
            "severity": "critical",
            "level": "block",
            "status": "open",
            "subject": "Arjun Berg",
            "others": 0,
            "ip": "198.51.100.58",
            "restricted": false,
            "created_at": "2026-09-25T00:14:51+00:00",
            "reviewed_at": null,
            "action_url": "/admin/fraud?flag=fflag_83p7w2fqfhevbgfg"
        }
    ],
    "meta": {
        "request_id": "req_01m50zckqgxx6nayka8bvz6nj1",
        "has_more": true,
        "next_cursor": "eyJzIjoiLXNjb3JlIiwidiI6WzAsLTkwLCItMTc5MDI5NTI5MS4wMDAwMDAiXSwiaWQiOiJmZmxhZ184M3A3dzJmcWZoZXZiZ2ZnIn0"
    }
}

| Field         | Description |
| ------------- | ----------- |
| `detector`    | The detector's key, which never changes. A trading rule's flag carries the rule's detector, such as `min_hold_time` |
| `category`    | Where the detector belongs: `ip`, `geo`, `device`, `linking`, `affiliate` or `trading` |
| `label`       | The detector's name in words, in the admin's language |
| `score`       | 5 to 100. `severity` follows from it: `low` under 40, `medium` under 60, `high` under 80, `critical` from 80 |
| `level`       | What the detector was set to when it raised the flag: `monitor`, `flag`, `restrict` or `block`. Null on a flag from before levels existed |
| `status`      | `open`, `auto_suspended` (it suspended somebody when it was raised), `resolved`, `dismissed`, or `ai_cleared`, which nothing sets yet |
| `subject`     | The first person the flag is about, null when it names nobody. `others` says how many more a group flag names |
| `ip`          | The address, a range such as `203.0.113.0/24` for a shared subnet, or null |
| `restricted`  | Whether the flag takes something away from somebody right now |
| `reviewed_at` | When somebody decided it, null while it is active |

## Errors

| Status | Code                      | Meaning                                                                                  |
| ------ | ------------------------- | ---------------------------------------------------------------------------------------- |
| 400    | `workspace_required`      | Asked by our own staff without naming a firm                                             |
| 400    | `validation_failed`       | `view`, `category`, `level` or `restricted` is not one of its values, or `q` is not text |
| 400    | `invalid_sort`            | `sort` is not one of the four orders                                                     |
| 400    | `invalid_limit`           | `limit` is not a positive integer                                                        |
| 400    | `invalid_cursor`          | `starting_after` is not a cursor handed out for this `sort`                              |
| 401    | `invalid_token`           | Not a token, or the secret does not match                                                |
| 401    | `revoked_token`           | Signed out here or from another device                                                   |
| 401    | `expired_token`           | Ninety days without use, or a set expiry passed                                          |
| 403    | `admin_access_required`   | This account no longer helps run the environment                                         |
| 403    | `insufficient_scope`      | This device does not hold `admin:read`                                                   |
| 403    | `workspace_not_permitted` | The `Propper-Workspace` header names an environment this account cannot act in           |
| 403    | `forbidden`               | Without `view_fraud`                                                                     |