> ## Documentation Index
> Fetch the complete documentation index at: https://chainpatrol.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Listar suspected threats

> List suspected threats for an organization using API key authentication, newest first. A suspected threat is an unconfirmed result of automated threat detection; use the `blockStatus` filter to find the ones confirmed as threats. Returns human-readable confidence levels (none, low, medium, high) and report status. Supports filtering by source, confidence level, raw score range, asset status, asset type and creation time, plus search. Pages hold up to 1000 results: pass `nextCursor` back as `cursor` until it is absent, set `includeTotal` to get the number of matching suspected threats without paging, and use `startDate` to fetch only suspected threats created since your last sync.

## Descripción general

Lista las **Suspected Threats** (amenazas sospechosas detectadas automáticamente, todavía sin confirmar) de tu organización: **Assets** (activos digitales: URL, direcciones, perfiles, apps, etc.) que la detección
automatizada de ChainPatrol marcó. Una suspected threat no está confirmada hasta que se revisa y
se bloquea. Usa el filtro `blockStatus` que aparece más abajo para seleccionar las que ya fueron
confirmadas.

La API conserva el nombre "detection": el endpoint es `/detection/list`, los resultados vienen
en el arreglo `detections` y cada elemento es un resultado de detección.

## Inicio rápido

### Autenticación

Incluye tu clave de API en el encabezado `X-API-KEY`:

```bash theme={null}
X-API-KEY: <api-key>
```

### Solicitud de ejemplo

```bash theme={null}
curl --request POST \
  --url https://app.chainpatrol.io/api/v2/detection/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "slug": "your-org",
    "limit": 50,
    "query": "phishing",
    "filters": [
      {
        "property": "source",
        "operator": "in",
        "value": ["EXTERNAL", "GOOGLE_SEARCH"]
      },
      {
        "property": "assetStatus",
        "operator": "in",
        "value": ["BLOCKED"]
      },
      {
        "property": "confidence",
        "operator": "in",
        "value": ["high", "medium"]
      }
    ]
  }'
```

## Esquema de la solicitud

### Cuerpo de la solicitud

| Campo | Tipo | Obligatorio | Valor predeterminado | Restricciones | Descripción |
| - | - | - | - | - | - |
| `slug` | `string` | ✅ Sí | - | - | Identificador (slug) de la organización |
| `cursor` | `number` | ❌ No | - | - | `nextCursor` de la respuesta anterior |
| `limit` | `number` | ❌ No | `50` | Mín.: 1, Máx.: 1000 | Cantidad de resultados por página |
| `filters` | `Filter[]` | ❌ No | `[]` | - | Arreglo de objetos de filtro |
| `query` | `string` | ❌ No | `""` | - | Consulta de búsqueda sobre el contenido de la amenaza (no distingue mayúsculas de minúsculas) |
| `startDate` | `string` | ❌ No | - | Formato ISO 8601 | Solo las suspected threats creadas en este momento o después |
| `endDate` | `string` | ❌ No | - | Formato ISO 8601 | Solo las suspected threats creadas en este momento o antes |
| `minScore` | `number` | ❌ No | - | 0–1, inclusivo | Solo las suspected threats cuyo `score` sin procesar es al menos este valor |
| `maxScore` | `number` | ❌ No | - | 0–1, inclusivo | Solo las suspected threats cuyo `score` sin procesar es como máximo este valor |
| `includeTotal` | `boolean` | ❌ No | `false` | - | Devuelve también `total`, la cantidad de coincidencias en todas las páginas |

> [!WARNING]
>
> `startDate` y `endDate` filtran según cuándo se creó la **suspected threat**, no
> según cuándo el asset se vio por primera vez, se reportó o se bloqueó. Omite ambos cuando quieras
> todas las suspected threats: un rango de fechas deja fuera en silencio el historial más antiguo, lo que se interpreta
> como resultados faltantes y no como un filtro.

### Esquema del filtro

Cada objeto de filtro debe tener la siguiente estructura:

| Campo | Tipo | Obligatorio | Descripción |
| - | - | - | - |
| `property` | `string` | ✅ Sí | Propiedad del filtro (consulta las opciones más abajo) |
| `operator` | `string` | ✅ Sí | `"in"` o `"notIn"` |
| `value` | `string[]` | ✅ Sí | Arreglo de valores por los que se filtra |

#### Propiedades del filtro

**1. Filtro de fuente (`"source"`)**

```typescript theme={null}
{
  "property": "source",
  "operator": "in" | "notIn",
  "value": ThreatDetectionSourceKey[]
}
```

> [accordion] Valores de fuente disponibles
>
> * `"ASSET_CHECK"` - Verificaciones de assets
> * `"BING_SEARCH"` - Resultados de búsqueda de Bing
> * `"CERTSTREAM"` - Registros de transparencia de certificados
> * `"DNS_TWIST"` - Detección con DNS twist
> * `"DUCK_DUCK_GO_SEARCH"` - Resultados de búsqueda de DuckDuckGo
> * `"EXTERNAL"` - Envíos externos de amenazas
> * `"GOOGLE_SEARCH"` - Resultados de búsqueda de Google
> * `"GUESTBOOK"` - Envíos de Guestbook
> * `"MEDIUM_TAG_RSS"` - Feeds RSS de Medium
> * `"MOZILLA_ADDON_SEARCH"` - Búsquedas de complementos de Mozilla
> * `"REDDIT_SUBREDDIT_SEARCH"` - Búsquedas en subreddits de Reddit
> * `"TWITTER"` - Monitoreo de Twitter
> * `"TWITTER_POST_SEARCH"` - Búsquedas de publicaciones de Twitter
> * `"TWITTER_SEARCH"` - Resultados de búsqueda de Twitter
> * `"URLSCAN"` - Resultados de URLScan.io
> * `"YAHOO_SEARCH"` - Resultados de búsqueda de Yahoo
> * `"YANDEX_IMAGE_SEARCH"` - Resultados de la búsqueda inversa de imágenes de Yandex para las imágenes de tu marca
> * `"YOUTUBE_SEARCH"` - Resultados de búsqueda de YouTube

**2. Filtro de estado del asset (`"assetStatus"`)**

```typescript theme={null}
{
  "property": "assetStatus",
  "operator": "in" | "notIn",
  "value": AssetStatus[]
}
```

**Valores de estado del asset disponibles:**

* `"UNKNOWN"` - Estado aún no determinado
* `"ALLOWED"` - El asset es legítimo/está permitido
* `"BLOCKED"` - El asset está bloqueado/es malicioso

**3. Filtro de confianza (`"confidence"`)**

```typescript theme={null}
{
  "property": "confidence",
  "operator": "in" | "notIn",
  "value": ConfidenceLevel[]
}
```

**Valores de nivel de confianza disponibles:**

* `"none"` - No se alcanzó ningún umbral de confianza
* `"low"` - Suspected threat de confianza baja
* `"medium"` - Suspected threat de confianza media
* `"high"` - Suspected threat de confianza alta

**4. Filtro de estado de bloqueo (`"blockStatus"`)**

```typescript theme={null}
{
  "property": "blockStatus",
  "operator": "in" | "notIn",
  "value": ("blocked" | "pending")[]
}
```

Selecciona las suspected threats cuyo asset ya se convirtió en una **amenaza confirmada**:

* `"blocked"` - el asset está en la **Blocklist** (lista de bloqueo) (`asset.status` es `"BLOCKED"`)
* `"pending"` - se confirmó que el asset es malicioso, pero todavía no se aplica el bloqueo
  porque la protección no está activa para tu organización
  (`asset.pendingStatus` es `"BLOCKED"`). La app de ChainPatrol las etiqueta como
  **Pending Blocked** (bloqueo pendiente).

Pasa ambos valores para obtener todas las amenazas confirmadas, tal como las cuenta la app. El
filtro `assetStatus` solo ve `asset.status`, así que `assetStatus: ["BLOCKED"]`
deja fuera los bloqueos pendientes.

**5. Filtro de eliminadas (`"deleted"`)**

```typescript theme={null}
{
  "property": "deleted",
  "operator": "in" | "notIn",
  "value": ["deleted"]
}
```

Las suspected threats eliminadas se **incluyen de forma predeterminada**. Agrega
`{ "property": "deleted", "operator": "notIn", "value": ["deleted"] }` para dejarlas
fuera, o usa `"in"` para devolver solo las eliminadas.

**6. Filtro de tipo de asset (`"assetType"`)**

```typescript theme={null}
{
  "property": "assetType",
  "operator": "in" | "notIn",
  "value": AssetType[]
}
```

> [accordion] Valores de tipo de asset disponibles
>
> * `"URL"` - URL de sitios web
> * `"PAGE"` - Páginas web
> * `"ADDRESS"` - Direcciones de blockchain
> * `"TWITTER"` - Perfiles/publicaciones de Twitter
> * `"FACEBOOK"` - Perfiles/páginas de Facebook
> * `"YOUTUBE"` - Canales/videos de YouTube
> * `"REDDIT"` - Publicaciones/subreddits de Reddit
> * `"TELEGRAM"` - Canales/grupos de Telegram
> * `"DISCORD"` - Servidores de Discord (obsoleto)
> * `"DISCORD_USER"` - Usuarios de Discord
> * `"LINKEDIN"` - Perfiles de LinkedIn
> * `"INSTAGRAM"` - Perfiles de Instagram
> * `"THREADS"` - Perfiles de Threads
> * `"TIKTOK"` - Perfiles de TikTok
> * `"MEDIUM"` - Artículos/perfiles de Medium
> * `"EMAIL"` - Direcciones de correo electrónico
> * `"WHATSAPP"` - Contactos de WhatsApp
> * `"GOOGLE_APP_STORE"` - Apps de Google Play Store
> * `"APPLE_APP_STORE"` - Apps de Apple App Store
> * `"AMAZON_APP_STORE"` - Apps de Amazon App Store
> * `"MICROSOFT_APP_STORE"` - Apps de Microsoft Store
> * `"CHROME_WEB_STORE"` - Extensiones de Chrome
> * `"MOZILLA_ADDONS"` - Complementos de Firefox
> * `"OPERA_ADDONS"` - Complementos de Opera
> * `"PATREON"` - Perfiles de Patreon
> * `"OPENSEA"` - Colecciones/perfiles de OpenSea
> * `"FARCASTER"` - Perfiles de Farcaster
> * `"IPFS"` - Hashes de IPFS
> * `"GOOGLE_FORM"` - Google Forms
> * `"QUORA"` - Perfiles/publicaciones de Quora
> * `"GITHUB"` - Repositorios/perfiles de GitHub
> * `"TEACHABLE"` - Cursos de Teachable
> * `"SUBSTACK"` - Publicaciones de Substack
> * `"DEBANK"` - Perfiles de DeBank
> * `"TAWK_TO"` - Widgets de chat de Tawk.to
> * `"JOTFORM"` - Formularios de JotForm
> * `"PRIMAL"` - Perfiles de Primal
> * `"BLUESKY"` - Perfiles de Bluesky
> * `"SNAPCHAT"` - Perfiles de Snapchat
> * `"DESO"` - Perfiles de DeSo

## Esquema de la respuesta

### Cuerpo de la respuesta

```typescript theme={null}
{
  detections: DetectionResult[];
  nextCursor?: number; // omitted on the last page
  total?: number; // only when includeTotal is true
}
```

### Objeto de resultado de detección

Cada elemento del arreglo `detections` es una suspected threat, con la siguiente
estructura:

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | `number` | Identificador único del resultado de detección de amenazas |
| `threatContent` | `string` | Contenido que se detectó como amenaza |
| `source` | `string` | Fuente de detección que lo encontró (ThreatDetectionSourceKey) |
| `createdAt` | `string` | Marca de tiempo ISO 8601 del momento en que se detectó |
| `confidence` | `string` | Nivel de confianza: `"none"`, `"low"`, `"medium"` o `"high"` |
| `score` | `number` | Puntaje sin procesar del modelo (0–1) a partir del cual se agrupa `confidence` |
| `reportStatus` | `string` | Estado del reporte: `"REPORTED"` o `"NOT_REPORTED"` |
| `asset` | `AssetObject` | Información del asset asociado |

### Objeto de asset

| Campo | Tipo | Descripción |
| - | - | - |
| `id` | `number` | Identificador único del asset |
| `content` | `string` | Contenido del asset (URL, dirección, nombre de usuario, etc.) |
| `type` | `string` | Tipo de asset (valor del enum AssetType) |
| `status` | `string` | Estado actual del asset (valor del enum AssetStatus) |
| `pendingStatus` | `string \| null` | Un estado ya revisado que todavía no entró en vigor. `"BLOCKED"` significa que se confirmó como malicioso, pero no se aplica porque la protección no está activa ("Pending Blocked"). `null` cuando no hay nada pendiente. |

### Ejemplo de respuesta completa

```json theme={null}
{
  "detections": [
    {
      "id": 12345,
      "threatContent": "Phishing site detected mimicking legitimate service",
      "source": "GOOGLE_SEARCH",
      "createdAt": "2024-01-15T10:30:00Z",
      "confidence": "high",
      "score": 0.97,
      "reportStatus": "REPORTED",
      "asset": {
        "id": 67890,
        "content": "https://fake-site.com",
        "type": "URL",
        "status": "BLOCKED",
        "pendingStatus": null
      }
    },
    {
      "id": 12346,
      "threatContent": "Suspicious crypto address found in scam report",
      "source": "EXTERNAL",
      "createdAt": "2024-01-15T09:15:00Z",
      "confidence": "medium",
      "score": 0.71,
      "reportStatus": "NOT_REPORTED",
      "asset": {
        "id": 67891,
        "content": "0x1234567890123456789012345678901234567890",
        "type": "ADDRESS",
        "status": "UNKNOWN",
        "pendingStatus": "BLOCKED"
      }
    }
  ],
  "nextCursor": 12347
}
```

## Conteos y umbrales de puntaje

Para contar las suspected threats sin tener que paginarlas, envía `includeTotal: true`.
La respuesta incluye entonces `total`: cuántas suspected threats coinciden con tus filtros,
tu búsqueda y tu rango de fechas en todas las páginas. Se cuenta antes de aplicar el cursor, así que cada
página de un recorrido informa el mismo número. Implica una consulta de conteo adicional, así que pídelo
en la primera página y no en todas.

`confidence` se agrupa a partir de `score` según los umbrales propios de tu organización, así que
`"high"` no equivale a un puntaje fijo. Para un umbral fijo, como "más del 80%", usa
`minScore` (y, si quieres, `maxScore`):

```bash theme={null}
curl --request POST \
  --url https://app.chainpatrol.io/api/v2/detection/list \
  --header 'Content-Type: application/json' \
  --header 'X-API-KEY: <api-key>' \
  --data '{
    "slug": "your-org",
    "limit": 10,
    "minScore": 0.8,
    "includeTotal": true,
    "filters": [
      { "property": "deleted", "operator": "notIn", "value": ["deleted"] }
    ]
  }'
```

Un `minScore` mayor que `maxScore` se rechaza con un `400`.

Consulta [Cómo evaluar las suspected threats](https://chainpatrol.com/docs/es/external-api/evaluating-detections.md) para ver las
preguntas que suele hacerse la gente cuando mira estos datos por primera vez, y la solicitud
que responde cada una.

## Paginación y sincronización incremental

Las suspected threats se devuelven de la más reciente a la más antigua. No hay una exportación en una sola llamada: una
organización puede tener cientos de miles de suspected threats, muchas más de las que caben
en una respuesta. En su lugar, recórrelas por páginas:

* Establece `limit` en hasta **1000**.
* Pasa el `nextCursor` de cada respuesta como `cursor`.
* Detente cuando una respuesta no tenga `nextCursor`.

> [!NOTE]
>
> Las respuestas tienen un tope de 4MB. Una página que lo supere falla con un error `413`
> en lugar de recortarse. Reintenta con un `limit` más pequeño. Una página de 1000 filas
> suele quedar muy por debajo de 1MB.

### Obtener solo las suspected threats nuevas

Después de una sincronización completa inicial, usa `startDate` para que cada ejecución solo obtenga lo que se
creó desde la anterior. Con 1,000 a 10,000 suspected threats nuevas por día, eso
equivale a unas pocas páginas de 1000 filas.

1. Registra la hora en que empieza la sincronización y envíala como `endDate`. Las suspected threats
   creadas mientras estás paginando quedan al frente del orden (de la más reciente a la más antigua), así que sin
   un `endDate` fijo se omitirían. En cambio, las toma la siguiente ejecución.
2. Establece `startDate` en la hora de inicio de la ejecución anterior, menos unos minutos de
   superposición. Una suspected threat puede tardar unos segundos en ser visible después de su
   `createdAt`, y la superposición la captura.
3. Pagina hasta que no haya `nextCursor` y elimina los duplicados por `id`. La superposición
   hace que algunas suspected threats aparezcan en dos ejecuciones.

Las suspected threats eliminadas se incluyen a menos que agregues
`{ "property": "deleted", "operator": "notIn", "value": ["deleted"] }` a
`filters`. Para obtener solo los dominios falsos sospechosos, agrega
`{ "property": "assetType", "operator": "in", "value": ["URL"] }`.

> [!WARNING]
>
> Una sincronización con `startDate` solo devuelve las suspected threats *creadas* dentro del rango. Si una
> suspected threat se reporta o se elimina después de que la obtuviste, la siguiente ejecución incremental
> no la volverá a devolver. Ejecuta una sincronización completa periódica (por ejemplo, diaria) si
> necesitas esos cambios.

```javascript JavaScript theme={null}
async function fetchDetections({ slug, startDate, endDate, filters = [] }) {
  const detections = new Map();
  let cursor;

  do {
    const response = await fetch("https://app.chainpatrol.io/api/v2/detection/list", {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-KEY": "<api-key>",
      },
      body: JSON.stringify({
        slug,
        limit: 1000,
        filters,
        ...(startDate ? { startDate } : {}),
        ...(endDate ? { endDate } : {}),
        ...(cursor ? { cursor } : {}),
      }),
    });
    if (!response.ok) {
      throw new Error(`detection/list failed: ${response.status}`);
    }
    const data = await response.json();
    for (const detection of data.detections) {
      detections.set(detection.id, detection);
    }
    cursor = data.nextCursor;
  } while (cursor);

  return [...detections.values()];
}

// Incremental run: everything created since the previous run started.
const OVERLAP_MS = 5 * 60 * 1000;
const syncStartedAt = new Date();
const previousSyncStartedAt = new Date("2026-09-24T00:00:00Z"); // load from your store

const newDetections = await fetchDetections({
  slug: "your-org",
  startDate: new Date(previousSyncStartedAt.getTime() - OVERLAP_MS).toISOString(),
  endDate: syncStartedAt.toISOString(),
  filters: [{ property: "assetType", operator: "in", value: ["URL"] }],
});
// Save `syncStartedAt` as the next run's `previousSyncStartedAt`.
```

```python Python theme={null}
from datetime import datetime, timedelta, timezone

import requests

def fetch_detections(slug, start_date=None, end_date=None, filters=None):
    detections = {}
    cursor = None
    while True:
        body = {"slug": slug, "limit": 1000, "filters": filters or []}
        if start_date:
            body["startDate"] = start_date.isoformat()
        if end_date:
            body["endDate"] = end_date.isoformat()
        if cursor:
            body["cursor"] = cursor
        response = requests.post(
            "https://app.chainpatrol.io/api/v2/detection/list",
            headers={"Content-Type": "application/json", "X-API-KEY": "<api-key>"},
            json=body,
        )
        response.raise_for_status()
        data = response.json()
        for detection in data["detections"]:
            detections[detection["id"]] = detection
        cursor = data.get("nextCursor")
        if not cursor:
            break
    return list(detections.values())

# Incremental run: everything created since the previous run started.
sync_started_at = datetime.now(timezone.utc)
previous_sync_started_at = datetime(2026, 9, 24, tzinfo=timezone.utc)  # load from your store

new_detections = fetch_detections(
    "your-org",
    start_date=previous_sync_started_at - timedelta(minutes=5),
    end_date=sync_started_at,
    filters=[{"property": "assetType", "operator": "in", "value": ["URL"]}],
)
# Save `sync_started_at` as the next run's `previous_sync_started_at`.
```

## Control de acceso

La API aplica un control de acceso estricto según tu clave de API:

1. **Claves de API de organización**:

   * Solo pueden acceder a las suspected threats de la organización a la que están asociadas
   * Deben coincidir exactamente con el parámetro `slug`
   * Ejemplo: una clave de API de "acme-org" solo puede consultar resultados de "acme-org"

2. **Claves de API de usuario**:
   * Pueden acceder a las suspected threats de cualquier organización de la que el usuario sea miembro
   * Requieren que el usuario sea un miembro activo de la organización consultada

Si intentas consultar una organización sin los permisos adecuados, recibirás un error 403 Forbidden con el mensaje: "API key does not have access to this organization"

## Implementación de ejemplo

```javascript JavaScript theme={null}
async function fetchDetectionResults(params) {
  const response = await fetch("https://app.chainpatrol.io/api/v2/detection/list", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "<api-key>",
    },
    body: JSON.stringify(params),
  });
  return response.json();
}

// Example usage
fetchDetectionResults({
  slug: "your-org",
  limit: 50,
  query: "phishing",
  filters: [
    {
      property: "assetStatus",
      operator: "in",
      value: ["BLOCKED"],
    },
    {
      property: "assetType",
      operator: "in",
      value: ["URL", "ADDRESS"],
    },
  ],
  startDate: "2024-01-01T00:00:00Z",
  endDate: "2024-03-01T00:00:00Z",
})
  .then((data) => {
    console.log("Detection results:", data.detections);
    console.log("Next cursor:", data.nextCursor);
  })
  .catch((error) => console.error("Error fetching results:", error));
```

```typescript TypeScript theme={null}
interface DetectionFilter {
  property:
    | "source"
    | "assetStatus"
    | "blockStatus"
    | "deleted"
    | "assetType"
    | "confidence";
  operator: "in" | "notIn";
  value: string[];
}

interface DetectionListParams {
  slug: string;
  cursor?: number;
  limit?: number;
  filters?: DetectionFilter[];
  query?: string;
  startDate?: string;
  endDate?: string;
  minScore?: number;
  maxScore?: number;
  includeTotal?: boolean;
}

interface AssetObject {
  id: number;
  content: string;
  type: string;
  status: string;
  pendingStatus: string | null;
}

interface DetectionResult {
  id: number;
  threatContent: string;
  source: string;
  createdAt: string;
  confidence: "none" | "low" | "medium" | "high";
  score: number;
  reportStatus: "REPORTED" | "NOT_REPORTED";
  asset: AssetObject;
}

interface DetectionListResponse {
  detections: DetectionResult[];
  nextCursor?: number;
  total?: number;
}

async function fetchDetectionResults(
  params: DetectionListParams
): Promise<DetectionListResponse> {
  const response = await fetch("https://app.chainpatrol.io/api/v2/detection/list", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-API-KEY": "<api-key>",
    },
    body: JSON.stringify(params),
  });
  return response.json();
}

// Example usage
fetchDetectionResults({
  slug: "your-org",
  limit: 50,
  filters: [
    {
      property: "source",
      operator: "in",
      value: ["GOOGLE_SEARCH", "EXTERNAL"],
    },
    {
      property: "assetStatus",
      operator: "in",
      value: ["BLOCKED"],
    },
  ],
})
  .then((data) => {
    console.log(`Found ${data.detections.length} detection results`);
    data.detections.forEach((item) => {
      console.log(`Threat: ${item.threatContent}`);
      console.log(`Asset: ${item.asset.content} (${item.asset.type})`);
      console.log(`Status: ${item.asset.status}`);
      console.log(`Confidence: ${item.confidence}`);
      console.log(`Report Status: ${item.reportStatus}`);
      console.log("---");
    });

    if (data.nextCursor) {
      console.log("More results available with cursor:", data.nextCursor);
    }
  })
  .catch((error) => console.error("Error fetching results:", error));
```


## OpenAPI

````yaml POST /detection/list
openapi: 3.0.3
info:
  title: ChainPatrol External API - OpenAPI 3.0
  description: ChainPatrol External API documentation
  version: 2.0.0
servers:
  - url: https://app.chainpatrol.io/api/v2
security: []
tags:
  - name: asset
  - name: report
  - name: dark-web
externalDocs:
  url: https://chainpatrol.com/docs
paths:
  /detection/list:
    post:
      tags:
        - detection
      summary: List suspected threats for organization
      description: >-
        List suspected threats for an organization using API key authentication,
        newest first. A suspected threat is an unconfirmed result of automated
        threat detection; use the `blockStatus` filter to find the ones
        confirmed as threats. Returns human-readable confidence levels (none,
        low, medium, high) and report status. Supports filtering by source,
        confidence level, raw score range, asset status, asset type and creation
        time, plus search. Pages hold up to 1000 results: pass `nextCursor` back
        as `cursor` until it is absent, set `includeTotal` to get the number of
        matching suspected threats without paging, and use `startDate` to fetch
        only suspected threats created since your last sync.
      operationId: detectionList
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                slug:
                  type: string
                  description: Organization slug
                cursor:
                  type: number
                  description: >-
                    Pass the `nextCursor` from the previous response to fetch
                    the next page. Omit it for the first page.
                limit:
                  type: number
                  minimum: 1
                  maximum: 1000
                  default: 50
                  description: >-
                    Number of results per page, between 1 and 1000. Defaults to
                    50.
                filters:
                  type: array
                  items:
                    oneOf:
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - source
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - meta_ads_search
                                - telegram_channels_search_vetric
                                - telegram_user_search_vetric
                                - facebook_page_search_vetric
                                - facebook_user_search_vetric
                                - facebook_post_search_vetric
                                - instagram_account_search_vetric
                                - twitter_search_vetric
                                - meta_ads_search_vetric
                                - tik_tok_user_search_vetric
                                - tik_tok_video_search_vetric
                                - blocklist
                                - apple_app_store
                                - google_ads_search
                                - google_ads_transparency_search
                                - mozilla_addon_search
                                - asset_check
                                - twitter_post_search
                                - medium_tag_rss
                                - twitter_search
                                - yahoo_search
                                - duck_duck_go_search
                                - bing_search
                                - guestbook
                                - certstream
                                - external
                                - google_search
                                - dns_twist
                                - twitter
                                - twitter_username_monitor
                                - urlscan
                                - urlscan_hostname_search
                                - youtube_search
                                - google_play_search
                                - blocked_ip_scan
                                - blocked_bilibili_suggested
                                - grok_post_search
                                - grok_user_search
                                - google_lens_image_search
                                - yandex_search
                                - yandex_image_search
                                - linkedin_employee_detection
                                - linkedin_post_search
                                - linkedin_company_search
                                - dnsdb
                                - daily_motion_search
                                - watchlist
                                - github_search
                                - pump_fun_token_search
                                - dnsdb_watched_parents
                                - ct_log_search
                                - spamhaus_passive_dns
                                - spamhaus_zrd_dbl
                                - ranger
                                - reddit_subreddit_search
                                - adlibrary_ads_search
                                - dexscreener_search
                                - tik_tok_user_search
                                - tik_tok_video_search
                                - tik_tok_ads_search
                                - linkedin_people_search_vetric
                                - linkedin_company_search_vetric
                                - bing_ads_search
                                - telegram_user_search
                                - telegram_channels_search
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - confidence
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - none
                                - low
                                - medium
                                - high
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - liveness
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - UNKNOWN
                                - ALIVE
                                - DEAD
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - watchlist
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - ENABLED
                                - DISABLED
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - assetStatus
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - UNKNOWN
                                - ALLOWED
                                - BLOCKED
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - blockStatus
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - blocked
                                - pending
                        required:
                          - property
                          - operator
                          - value
                        description: >-
                          Filter by whether the asset is a confirmed threat.
                          `blocked` matches assets on the blocklist
                          (`asset.status` is `BLOCKED`); `pending` matches
                          assets confirmed malicious but not yet enforced
                          because protection is not active
                          (`asset.pendingStatus` is `BLOCKED`). Pass both to get
                          every confirmed threat, the way the ChainPatrol app
                          counts them.
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - reported
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - reported
                                - not_reported
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - assetType
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - URL
                                - PAGE
                                - ADDRESS
                                - DISCORD
                                - LINKEDIN
                                - TWITTER
                                - FACEBOOK
                                - YOUTUBE
                                - REDDIT
                                - TELEGRAM
                                - GOOGLE_APP_STORE
                                - APPLE_APP_STORE
                                - AMAZON_APP_STORE
                                - MICROSOFT_APP_STORE
                                - TIKTOK
                                - INSTAGRAM
                                - THREADS
                                - MEDIUM
                                - CHROME_WEB_STORE
                                - MOZILLA_ADDONS
                                - OPERA_ADDONS
                                - EMAIL
                                - PATREON
                                - OPENSEA
                                - FARCASTER
                                - IPFS
                                - GOOGLE_FORM
                                - WHATSAPP
                                - DISCORD_USER
                                - QUORA
                                - GITHUB
                                - TEACHABLE
                                - SUBSTACK
                                - DEBANK
                                - TAWK_TO
                                - JOTFORM
                                - PRIMAL
                                - BLUESKY
                                - SNAPCHAT
                                - DESO
                                - PINTEREST
                                - FLICKR
                                - GALXE
                                - VELOG
                                - NPM
                                - PYPI
                                - HEX
                                - DOCKER_HUB
                                - VOCAL_MEDIA
                                - TECKFINE
                                - TENDERLY
                                - HACKMD
                                - ETSY
                                - ZAZZLE
                                - BASENAME
                                - BILIBILI_TV
                                - VIMEO
                                - DAILYMOTION
                                - PHONE_NUMBER
                                - SLACK
                                - CALENDLY
                                - NGROK
                                - RARIBLE
                                - RUST_PACKAGE
                                - FLATHUB
                                - VIDLII
                                - VEVIOZ
                                - ISSUU
                                - SOUNDCLOUD
                                - ZAPPER
                                - REDNOTE
                                - SAMSUNG_APP_STORE
                                - HUAWEI_APP_STORE
                                - XIAOMI_APP_STORE
                                - TENCENT_APP_STORE
                                - OPPO_APP_STORE
                                - VIVO_APP_STORE
                                - F_DROID
                                - GOOGLE_AD
                                - BING_AD
                                - TWITCH
                                - BEHANCE
                                - ZORA
                                - META_AD
                                - SIGNAL
                                - DEVIANTART
                                - BANDCAMP
                                - ARCHIVE_ORG
                                - FIVE_HUNDRED_PX
                                - LUMA
                                - SMARTMONEYMATCH
                                - APK_GOLD
                                - GLASSDOOR
                                - PUMP_FUN
                                - TUMBLR
                                - MASTODON
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - brand
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: number
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - deleted
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              enum:
                                - deleted
                        required:
                          - property
                          - operator
                          - value
                      - type: object
                        properties:
                          property:
                            type: string
                            enum:
                              - countryCode
                          operator:
                            type: string
                            enum:
                              - in
                              - notIn
                          value:
                            type: array
                            items:
                              type: string
                              minLength: 2
                              maxLength: 2
                        required:
                          - property
                          - operator
                          - value
                  default: []
                  description: Filters to apply to the results
                query:
                  type: string
                  default: ''
                  description: Search query for threat content
                minScore:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: >-
                    Only return suspected threats whose raw `score` is at least
                    this value (inclusive, 0-1). Use this rather than the
                    `confidence` filter when you need a fixed cut-off such as
                    0.8: `confidence` buckets depend on your organization's
                    thresholds.
                maxScore:
                  type: number
                  minimum: 0
                  maximum: 1
                  description: >-
                    Only return suspected threats whose raw `score` is at most
                    this value (inclusive, 0-1). Must not be below `minScore`.
                includeTotal:
                  type: boolean
                  default: false
                  description: >-
                    Also return `total`: how many suspected threats match the
                    filters, search and date range across all pages. Costs an
                    extra count query, so request it on the first page of a
                    sweep rather than every page.
                startDate:
                  type: string
                  description: >-
                    Only return suspected threats created at or after this time
                    (inclusive). For incremental syncs, pass the time your
                    previous sync started minus a few minutes of overlap, and
                    de-duplicate by `id`.
                endDate:
                  type: string
                  description: >-
                    Only return suspected threats created at or before this time
                    (inclusive). Pin it to the time a sync starts so every page
                    of that sync sees the same result set.
              required:
                - slug
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                type: object
                properties:
                  detections:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: number
                        threatContent:
                          type: string
                        source:
                          anyOf:
                            - type: string
                              enum:
                                - meta_ads_search
                                - telegram_channels_search_vetric
                                - telegram_user_search_vetric
                                - facebook_page_search_vetric
                                - facebook_user_search_vetric
                                - facebook_post_search_vetric
                                - instagram_account_search_vetric
                                - twitter_search_vetric
                                - meta_ads_search_vetric
                                - tik_tok_user_search_vetric
                                - tik_tok_video_search_vetric
                                - blocklist
                                - apple_app_store
                                - google_ads_search
                                - google_ads_transparency_search
                                - mozilla_addon_search
                                - asset_check
                                - twitter_post_search
                                - medium_tag_rss
                                - twitter_search
                                - yahoo_search
                                - duck_duck_go_search
                                - bing_search
                                - guestbook
                                - certstream
                                - external
                                - google_search
                                - dns_twist
                                - twitter
                                - twitter_username_monitor
                                - urlscan
                                - urlscan_hostname_search
                                - youtube_search
                                - google_play_search
                                - blocked_ip_scan
                                - blocked_bilibili_suggested
                                - grok_post_search
                                - grok_user_search
                                - google_lens_image_search
                                - yandex_search
                                - yandex_image_search
                                - linkedin_employee_detection
                                - linkedin_post_search
                                - linkedin_company_search
                                - dnsdb
                                - daily_motion_search
                                - watchlist
                                - github_search
                                - pump_fun_token_search
                                - dnsdb_watched_parents
                                - ct_log_search
                                - spamhaus_passive_dns
                                - spamhaus_zrd_dbl
                                - ranger
                            - type: string
                          description: >-
                            Detection source key. Usually one of the current
                            source keys, but suspected threats from a retired
                            source keep their original key, so treat unknown
                            values as valid.
                        createdAt:
                          type: string
                        confidence:
                          type: string
                          enum:
                            - none
                            - low
                            - medium
                            - high
                        score:
                          type: number
                          description: >-
                            Raw model score (0-1). `confidence` is derived by
                            bucketing this into low/medium/high using the org's
                            thresholds; use this when the buckets are too
                            coarse.
                        reason:
                          type: string
                          description: >-
                            Free-text explanation of why this was flagged as a
                            suspected threat (e.g. 'matches brand-name typo
                            squat', 'TLS cert issued by known lookalike CA').
                            Read this before deciding what to do with a hit.
                        configId:
                          type: number
                          description: >-
                            ID of the `ThreatDetectionConfig` that produced this
                            hit. Combine with `run_chainpatrol
                            listDetectionConfigs` to drill back into the config.
                        reportedAt:
                          type: string
                          nullable: true
                          description: >-
                            When the suspected threat was reported (transitioned
                            to REPORTED status). `null` when it hasn't been
                            reported yet — `reportStatus` reflects the same
                            information as a categorical.
                        brands:
                          type: array
                          items:
                            type: object
                            properties:
                              id:
                                type: number
                              name:
                                type: string
                              slug:
                                type: string
                            required:
                              - id
                              - name
                              - slug
                          description: >-
                            Brands the suspected threat was associated with.
                            Empty when it was not linked to any brand at
                            classification time.
                        reportStatus:
                          type: string
                          enum:
                            - REPORTED
                            - NOT_REPORTED
                        asset:
                          type: object
                          properties:
                            id:
                              type: number
                            content:
                              type: string
                            type:
                              type: string
                              enum:
                                - URL
                                - PAGE
                                - ADDRESS
                                - DISCORD
                                - LINKEDIN
                                - TWITTER
                                - FACEBOOK
                                - YOUTUBE
                                - REDDIT
                                - TELEGRAM
                                - GOOGLE_APP_STORE
                                - APPLE_APP_STORE
                                - AMAZON_APP_STORE
                                - MICROSOFT_APP_STORE
                                - TIKTOK
                                - INSTAGRAM
                                - THREADS
                                - MEDIUM
                                - CHROME_WEB_STORE
                                - MOZILLA_ADDONS
                                - OPERA_ADDONS
                                - EMAIL
                                - PATREON
                                - OPENSEA
                                - FARCASTER
                                - IPFS
                                - GOOGLE_FORM
                                - WHATSAPP
                                - DISCORD_USER
                                - QUORA
                                - GITHUB
                                - TEACHABLE
                                - SUBSTACK
                                - DEBANK
                                - TAWK_TO
                                - JOTFORM
                                - PRIMAL
                                - BLUESKY
                                - SNAPCHAT
                                - DESO
                                - PINTEREST
                                - FLICKR
                                - GALXE
                                - VELOG
                                - NPM
                                - PYPI
                                - HEX
                                - DOCKER_HUB
                                - VOCAL_MEDIA
                                - TECKFINE
                                - TENDERLY
                                - HACKMD
                                - ETSY
                                - ZAZZLE
                                - BASENAME
                                - BILIBILI_TV
                                - VIMEO
                                - DAILYMOTION
                                - PHONE_NUMBER
                                - SLACK
                                - CALENDLY
                                - NGROK
                                - RARIBLE
                                - RUST_PACKAGE
                                - FLATHUB
                                - VIDLII
                                - VEVIOZ
                                - ISSUU
                                - SOUNDCLOUD
                                - ZAPPER
                                - REDNOTE
                                - SAMSUNG_APP_STORE
                                - HUAWEI_APP_STORE
                                - XIAOMI_APP_STORE
                                - TENCENT_APP_STORE
                                - OPPO_APP_STORE
                                - VIVO_APP_STORE
                                - F_DROID
                                - GOOGLE_AD
                                - BING_AD
                                - TWITCH
                                - BEHANCE
                                - ZORA
                                - META_AD
                                - SIGNAL
                                - DEVIANTART
                                - BANDCAMP
                                - ARCHIVE_ORG
                                - FIVE_HUNDRED_PX
                                - LUMA
                                - SMARTMONEYMATCH
                                - APK_GOLD
                                - GLASSDOOR
                                - PUMP_FUN
                                - TUMBLR
                                - MASTODON
                            status:
                              type: string
                              enum:
                                - UNKNOWN
                                - ALLOWED
                                - BLOCKED
                            pendingStatus:
                              type: string
                              nullable: true
                              enum:
                                - UNKNOWN
                                - ALLOWED
                                - BLOCKED
                                - null
                              description: >-
                                A reviewed status that has not taken effect yet,
                                or null when nothing is pending. `BLOCKED` here
                                means the asset was confirmed malicious but is
                                not enforced on the blocklist because protection
                                is not active for your organization — shown as
                                "Pending Blocked" in the ChainPatrol app. It
                                becomes `status` once protection is activated.
                          required:
                            - id
                            - content
                            - type
                            - status
                            - pendingStatus
                      required:
                        - id
                        - threatContent
                        - source
                        - createdAt
                        - confidence
                        - score
                        - reason
                        - configId
                        - reportedAt
                        - brands
                        - reportStatus
                        - asset
                  nextCursor:
                    type: number
                  total:
                    type: number
                    description: >-
                      How many suspected threats match the filters, search and
                      date range across all pages, regardless of `cursor`.
                      Present only when `includeTotal` is true.
                required:
                  - detections
        '400':
          description: Invalid input data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.BAD_REQUEST'
        '401':
          description: Authorization not provided
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.UNAUTHORIZED'
        '403':
          description: Insufficient access
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.FORBIDDEN'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error.INTERNAL_SERVER_ERROR'
      security:
        - ApiKey: []
components:
  schemas:
    error.BAD_REQUEST:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Invalid input data
        code:
          type: string
          description: The error code
          example: BAD_REQUEST
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Invalid input data error (400)
      description: The error information
      example:
        code: BAD_REQUEST
        message: Invalid input data
        issues: []
    error.UNAUTHORIZED:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Authorization not provided
        code:
          type: string
          description: The error code
          example: UNAUTHORIZED
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Authorization not provided error (401)
      description: The error information
      example:
        code: UNAUTHORIZED
        message: Authorization not provided
        issues: []
    error.FORBIDDEN:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Insufficient access
        code:
          type: string
          description: The error code
          example: FORBIDDEN
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Insufficient access error (403)
      description: The error information
      example:
        code: FORBIDDEN
        message: Insufficient access
        issues: []
    error.INTERNAL_SERVER_ERROR:
      type: object
      properties:
        message:
          type: string
          description: The error message
          example: Internal server error
        code:
          type: string
          description: The error code
          example: INTERNAL_SERVER_ERROR
        issues:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
            required:
              - message
          description: An array of issues that were responsible for the error
          example: []
      required:
        - message
        - code
      title: Internal server error error (500)
      description: The error information
      example:
        code: INTERNAL_SERVER_ERROR
        message: Internal server error
        issues: []
  securitySchemes:
    ApiKey:
      type: apiKey
      in: header
      name: X-API-KEY
      description: >-
        Your API key. This is required by most endpoints to access our API
        programatically. Reach out to us at
        [support@chainpatrol.io](mailto:support@chainpatrol.io?subject=Re:%20API%20Key%20for%20SDK&body=Company:%20%0AName:%20%0APurpose:%20)
        to get an API key for your use.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.