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

# List bots

> Lists the instance's Typebot bots (or a single one) with live enrichment and the integration status

**Auth:** `TokenAccount` or `TokenInstance` • **Rate limit:** `Global` (100/min) • **Idempotent:** yes

## Description

Returns the Typebot bots registered on the instance, along with the `status` and `last_error` of the integration. Pass `?botId=` to return a **single** bot instead of the whole list. The local status is complemented (best-effort) with the live integration state, with a **10s** timeout; if the live state is unavailable, the local values are kept.

<Note>
  Each bot now carries **live enrichment**: `active_sessions` (count of opened + paused sessions for that bot) and `last_activity_at` (timestamp of the last activity, RFC3339, absent when the bot never ran).
</Note>

<Note>
  This endpoint does **not** return `503` when the integration is unavailable: it responds with local data and, if any, a `last_error`. The `503 integration gateway not configured` only appears in `set`, `update` and `start`.
</Note>

## Example

**All 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>

**A single bot**

<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",
      headers={
          "token": os.environ["Token_Account"]
      },
      params={ "botId": "8f3a1c2e-...-b7d9" }
  )
  ```

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

## Success response

```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 }
}
```

| Field        | Description                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------- |
| `success`    | Always `true` on success.                                                                           |
| `message`    | Human-readable count (`N bot(s) found`).                                                            |
| `status`     | State of the integration: `active` / `paused` / `error`. Empty when there is no active integration. |
| `last_error` | Last error message from the integration. Empty when healthy.                                        |
| `bots`       | List of the instance's bots (a single item when `?botId=` is used). Empty when there are no bots.   |
| `meta.total` | Number of bots returned.                                                                            |

### Bot fields

| Field              | Description                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------- |
| `id`               | Bot UUID.                                                                                               |
| `instance_id`      | Internal ID of the instance that owns the bot.                                                          |
| `enabled`          | Whether the bot is active in routing.                                                                   |
| `description`      | Bot label in the panel.                                                                                 |
| `typebot_url`      | URL of the published Typebot (viewer).                                                                  |
| `trigger_type`     | `all` or `keyword`.                                                                                     |
| `trigger_operator` | `contains` / `equals` / `startsWith` / `endsWith` / `regex` (present when `trigger_type` is `keyword`). |
| `trigger_value`    | Trigger word/expression (present when `trigger_type` is `keyword`).                                     |
| `expire_minutes`   | Minutes of inactivity until the session expires (`0` = never).                                          |
| `expire_message`   | Message sent when the session expires.                                                                  |
| `keyword_finish`   | Word that ends the bot.                                                                                 |
| `finish_message`   | Farewell sent when ended by keyword.                                                                    |
| `typing_delay_ms`  | Delay of the "typing..." before each reply (ms).                                                        |
| `stop_bot_from_me` | Pauses the bot when the operator replies in the conversation.                                           |
| `debounce_seconds` | Seconds of fragment grouping before processing.                                                         |
| `ignore_groups`    | Ignores group messages.                                                                                 |
| `no_start_from_me` | Do not auto-start the bot when the operator started the conversation.                                   |
| `keep_open`        | Keep the conversation open when the flow ends, status `held`.                                           |
| `active_sessions`  | **Enrichment**, number of live sessions (opened + paused) for this bot.                                 |
| `last_activity_at` | **Enrichment**, timestamp of the last activity (RFC3339). Absent when the bot never ran.                |
| `created_at`       | When the bot was created (RFC3339).                                                                     |
| `updated_at`       | When the bot was last updated (RFC3339).                                                                |

## Path parameters

<ParamField path="instance" type="string" required>
  Instance name (e.g., `suporte`).
</ParamField>

## Query parameters

<ParamField query="botId" type="string">
  UUID of a single bot to return. Omitted, all the instance's bots are listed.
</ParamField>

## Headers

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

## Behavior

<Steps>
  <Step title="Read the local bots">
    Queries the instance's `typebot_bots` table (filtered by `botId` when supplied). This step is fast and always works.
  </Step>

  <Step title="Enrich with live session data">
    For each bot, RyzeAPI counts the opened + paused sessions (`active_sessions`) and resolves the `last_activity_at`.
  </Step>

  <Step title="Read the integration link">
    Fetches the row in `typebot_integrations` to get the local `status` and `last_error`.
  </Step>

  <Step title="Complement with the live integration state (best-effort)">
    If there is an active integration, RyzeAPI queries the current state with a **10s** timeout and overwrites `status` / `last_error` with the live values. On network failure, it keeps the local ones.
  </Step>
</Steps>

## Errors

| HTTP | `error.message`      |
| :--: | -------------------- |
|  404 | `instance not found` |

## Next

<CardGroup cols={2}>
  <Card title="Live sessions" icon="comments" href="/en/api/typebot/sessions">
    List and control ongoing conversations with `GET /api/typebot/sessions/:instance`.
  </Card>

  <Card title="Edit bot" icon="pen" href="/en/api/typebot/update">
    Change a bot's fields with `PATCH /api/typebot/update/:instance`.
  </Card>
</CardGroup>