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

# Listar bots

> Lista los bots de Typebot de la instancia (o uno solo con ?botId=) y el estado de la integración

**Auth:** `TokenAccount` o `TokenInstance` • **Rate limit:** `Global` (100/min) • **Idempotente:** sí

## Descripción

Devuelve los bots de Typebot registrados en la instancia, junto con el `status` y el `last_error` de la integración. Con el query param opcional `?botId=`, devuelve **solo ese bot** (útil para reemplazar el antiguo `find`). El estado local se complementa (best-effort) con el estado actual de la integración, con un timeout de **10 s**; si no responde, se mantienen los valores locales.

<Note>
  Cada bot llega **enriquecido** con métricas en vivo: `active_sessions` (número de sesiones abiertas + pausadas de ese bot) y `last_activity_at` (marca de tiempo RFC3339 de la última actividad, ausente si nunca hubo).
</Note>

<Note>
  Este endpoint **no** devuelve `503` cuando la integración no está disponible: responde con los datos locales y, si lo hay, un `last_error`. El `503 integration gateway not configured` solo aparece en `set`, `update` y `start`.
</Note>

## Ejemplo

**Todos los bots**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/typebot/list/suporte" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/typebot/list/suporte", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/typebot/list/suporte",
      headers={
          "token": os.environ["Token_Account"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/typebot/list/suporte", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

**Un bot específico (`?botId=`)**

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://ryzeapi.cloud/api/typebot/list/suporte?botId=8f3a1c2e-...-b7d9" \
    -H "token: $Token_Account"
  ```

  ```javascript JavaScript theme={null}
  await fetch("https://ryzeapi.cloud/api/typebot/list/suporte?botId=8f3a1c2e-...-b7d9", {
    method: "GET",
    headers: {
      "token": process.env.Token_Account
    }
  });
  ```

  ```python Python theme={null}
  import os, requests

  requests.get(
      "https://ryzeapi.cloud/api/typebot/list/suporte",
      params={"botId": "8f3a1c2e-...-b7d9"},
      headers={
          "token": os.environ["Token_Account"]
      }
  )
  ```

  ```go Go theme={null}
  package main

  import (
      "net/http"
      "os"
  )

  func main() {
      req, _ := http.NewRequest("GET", "https://ryzeapi.cloud/api/typebot/list/suporte?botId=8f3a1c2e-...-b7d9", nil)
      req.Header.Set("token", os.Getenv("Token_Account"))
      http.DefaultClient.Do(req)
  }
  ```
</CodeGroup>

## Respuesta exitosa

```json 200 OK theme={null}
{
  "success": true,
  "message": "1 bot(s) found",
  "status": "active",
  "last_error": "",
  "bots": [
    {
      "id": "8f3a1c2e-...-b7d9",
      "instance_id": "...",
      "enabled": true,
      "description": "Bot de orçamento",
      "typebot_url": "https://typebot.co/meu-bot-abc123",
      "trigger_type": "keyword",
      "trigger_operator": "contains",
      "trigger_value": "orçamento",
      "expire_minutes": 30,
      "expire_message": "Sessão encerrada por inatividade.",
      "keyword_finish": "sair",
      "finish_message": "Até logo! 👋",
      "typing_delay_ms": 1500,
      "stop_bot_from_me": true,
      "debounce_seconds": 6,
      "ignore_groups": true,
      "no_start_from_me": false,
      "keep_open": false,
      "active_sessions": 2,
      "last_activity_at": "2026-07-27T13:58:40Z",
      "created_at": "2026-07-20T09:12:00Z",
      "updated_at": "2026-07-27T14:05:22Z"
    }
  ],
  "meta": {
    "total": 1
  }
}
```

| Campo                     | Descripción                                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `success`                 | `true` cuando la operación tuvo éxito.                                                                        |
| `message`                 | Resumen: `N bot(s) found`.                                                                                    |
| `status`                  | Estado de la integración: `active` / `paused` / `error`. Vacío cuando no hay integración activa.              |
| `last_error`              | Último mensaje de error de la integración. Vacío cuando está saludable.                                       |
| `bots`                    | Lista de los bots de la instancia (o solo el bot filtrado con `?botId=`). Vacío cuando no hay bots.           |
| `bots[].active_sessions`  | **Enriquecimiento:** número de sesiones abiertas + pausadas de ese bot.                                       |
| `bots[].last_activity_at` | **Enriquecimiento:** marca de tiempo RFC3339 de la última actividad del bot. Ausente si nunca hubo actividad. |
| `meta.total`              | Número de bots devueltos.                                                                                     |

<Note>
  Los demás campos de cada bot (`id`, `enabled`, `typebot_url`, `trigger_*`, `expire_*`, `keyword_finish`, `finish_message`, `typing_delay_ms`, `stop_bot_from_me`, `debounce_seconds`, `ignore_groups`, `no_start_from_me`, `keep_open`, `created_at`, `updated_at`) son los mismos que se envían al [crear](/es/api/typebot/set) o [editar](/es/api/typebot/update) el bot.
</Note>

## Parámetros de ruta

<ParamField path="instance" type="string" required>
  Nombre de la instancia (p. ej., `suporte`).
</ParamField>

## Parámetros de consulta

<ParamField query="botId" type="string">
  UUID de un bot específico. Presente, la respuesta trae solo ese bot (reemplaza al antiguo `find`). Ausente, devuelve todos los bots de la instancia.
</ParamField>

## Cabeceras

<ParamField header="token" type="string" required>
  `TokenAccount` o `TokenInstance`.
</ParamField>

## Comportamiento

<Steps>
  <Step title="Lee los bots locales">
    Consulta la tabla `typebot_bots` de la instancia (o solo el bot indicado en `?botId=`). Este paso es rápido y siempre funciona.
  </Step>

  <Step title="Lee el vínculo de la integración">
    Busca la fila en `typebot_integrations` para obtener el `status` y el `last_error` locales.
  </Step>

  <Step title="Enriquece con métricas en vivo (best-effort)">
    Si hay integración disponible, RyzeAPI consulta el estado actual con un timeout de **10 s** y sobrescribe `status` / `last_error` con los valores en vivo, y agrega `active_sessions` + `last_activity_at` a cada bot. En caso de fallo de red, mantiene los locales.
  </Step>
</Steps>

## Errores

| HTTP | `error.message`                                                                  |
| :--: | -------------------------------------------------------------------------------- |
|  404 | `instance not found`                                                             |
|  404 | `bot not found for this instance` (solo cuando se pasa un `?botId=` inexistente) |

## Siguiente

<CardGroup cols={2}>
  <Card title="Editar bot" icon="pen" href="/es/api/typebot/update">
    Ajusta los campos de un bot con `PATCH /api/typebot/update/:instance`.
  </Card>

  <Card title="Sesiones en vivo" icon="comments" href="/es/api/typebot/sessions">
    Consulta y controla las conversaciones en curso con `GET/POST /api/typebot/sessions/:instance`.
  </Card>
</CardGroup>