# List Bots

> Lists every bot on the account: trader, signal and market bots, on paper and live.

Source: https://rivo.markets/docs/reference/list-bots

`GET /v2/bots`

Scope: `read`

This route returns the account's bots of all three kinds, each with its record. It lists bots you made in the app and bots you made through the API together.

- A **trader** bot copies one trader's buys.
- A **signal** bot copies every whale buy that matches its signal.
- A **market** bot runs a price rule on one market, or on every market of a repeating series.

Live bots appear with `mode: "live"`. You can set them up and change them only in the app.

## Example request

curl:

```bash
curl "https://api.rivo.markets/v2/bots?status=running" \
  -H "Authorization: Bearer rivo_live_..."
```

Python:

```python
import requests

url = "https://api.rivo.markets/v2/bots"
headers = {
    "Authorization": "Bearer rivo_live_...",
}
params = [
    ("status", "running"),
]

res = requests.get(url, headers=headers, params=params)
res.raise_for_status()
print(res.json())
```

TypeScript:

```typescript
const params = new URLSearchParams([
  ["status", "running"],
]);

const res = await fetch(`https://api.rivo.markets/v2/bots?${params}`, {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.RIVO_API_KEY}`,
  },
});
if (!res.ok) throw new Error(`Rivo API ${res.status}`);
const { data } = await res.json();
```

## Query parameters

- `kind` (string, optional): Returns bots of these kinds: `trader`, `signal` or `market`. Repeat the key to pass several.
- `status` (string, optional): Returns bots with these statuses: `running`, `paused` or `ended`. Repeat the key to pass several.
- `venue` (string, optional): Returns rows from these venues: `kalshi`, `polymarket`, `polymarket_us` or `gemini`. To pass several values, repeat the key, up to 50 times. A row matches if it matches any of them.
- `limit` (integer, optional, default `50`): The number of rows on each page, from 1 to 200.
- `cursor` (string, optional): Pass the `nextCursor` from the previous page to read the next one. A cursor works only on the listing that made it. See [Paging](https://rivo.markets/docs/concepts#paging).

## Example response

```json
{
  "data": [
    {
      "id": "trader:8d3f2a61-0c4e-4b7a-9f15-2e6a1c9b4d70",
      "name": "avidsmores",
      "kind": "trader",
      "mode": "paper",
      "summary": "Copies avidsmores",
      "status": "running",
      "venues": ["kalshi"],
      "trades": 14,
      "profit": 186.4,
      "winRate": 0.6,
      "lastTradeAt": "2026-10-12T05:13:31.000Z"
    },
    {
      "id": "signal:2c91e7d4-5a3b-4f08-b6e2-91d04f7a3c55",
      "name": "Kalshi sports buys, 30¢ to 70¢, $5,000 or more",
      "kind": "signal",
      "mode": "paper",
      "summary": "Kalshi sports buys, 30¢ to 70¢, $5,000 or more",
      "status": "running",
      "venues": ["kalshi"],
      "trades": 212,
      "profit": 523.17,
      "winRate": 0.5521,
      "lastTradeAt": "2026-10-15T01:58:12.000Z"
    }
  ],
  "nextCursor": null
}
```

## Response fields

- `data` (object[]): The bots on this page.
  - `id` (string): The bot's id: `trader:<id>`, `signal:<id>` or `market:<id>`.
  - `name` (string): The bot's name. A trader bot takes its trader's name, and a market bot takes the name of its market or series.
  - `kind` (string): The kind of bot. A `trader` bot copies one trader, a `signal` bot runs a signal, and a `market` bot runs a price rule on one market.
  - `mode` (string): Whether the bot trades on `paper` or `live`. A live bot trades real money. You set it up in the app, and the API can only read it.
  - `summary` (string): What the bot does, in one line.
  - `status` (string): The bot's status: `running`, `paused` or `ended`. A signal bot is never paused. It runs for as long as it exists.
  - `venues` (string[]): The venues the bot trades on.
  - `trades` (integer): The number of trades the bot took.
  - `profit` (number): The bot's profit in USD, from both closed and open trades.
  - `winRate` (number or null): The share of the bot's settled trades that won, from 0 to 1.
  - `lastTradeAt` (string or null): When the bot last traded, in ISO 8601 UTC.
- `nextCursor` (string or null): Pass this as `cursor` to read the next page. It is `null` on the last page.

## Errors

| Code | When |
| --- | --- |
| `VALIDATION` | A parameter is out of range or unknown, or the cursor came from another listing. |