# List sequences

> Your sequences, newest first.

`GET /v1/sequences`

Your sequences, newest first. Archived ones are left out unless you ask for `state=archived`.

Needs a key with the `messages:read` scope. [Keys and scopes](https://usebluebot.com/docs/concepts/api-keys)

## Query parameters

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `state` | string | No | One of `active`, `paused`, `archived` |
| `limit` | integer | No | How many to return, 1 to 100. Default 25. 1 to 100. Default `25` |
| `cursor` | string | No | The `next_cursor` of the page before. Leave it out for the first page. Up to 200 characters |

## Example

```bash
curl "https://usebluebot.com/api/v1/sequences" \
  -H "Authorization: Bearer $BLUEBOT_API_KEY"
```

```ts
import BlueBot from '@usebluebot/sdk';

const client = new BlueBot({ apiKey: process.env.BLUEBOT_API_KEY });

const page = await client.sequences.list();
console.log(page.data);
```

```python
import os
from bluebot import BlueBot

client = BlueBot(api_key=os.environ["BLUEBOT_API_KEY"])

page = client.sequences.list()
print(page.data)
```

## Response

`200`: A page of sequences.

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "list" | Yes |   |
| `data` | array of Sequence | Yes |   |
| `data[].id` | string | Yes | A seq_ id. Starts with `seq_` |
| `data[].object` | "sequence" | Yes |   |
| `data[].name` | string | Yes |   |
| `data[].description` | string or null | Yes |   |
| `data[].state` | string | Yes | `active` takes new people and sends; `paused` holds every enrollment where it is; `archived` ends them. One of `active`, `paused`, `archived` |
| `data[].stop_on_reply` | boolean | Yes | Stop a person’s run when they text back. On unless you turn it off. A stop word always stops it. |
| `data[].send_window` | object or null | Yes | When steps may send, in your time zone. A step due outside it waits for it to open. |
| `data[].send_window.days` | array of strings | Yes | The days it may send on. One of `mon`, `tue`, `wed`, `thu`, `fri`, `sat`, `sun` |
| `data[].send_window.start` | string | Yes | A time of day as HH:MM in your account’s time zone. |
| `data[].send_window.end` | string | Yes | A time of day as HH:MM in your account’s time zone. |
| `data[].steps` | array of SequenceStep | Yes |   |
| `data[].steps[].id` | string | Yes | A step_ id. Starts with `step_` |
| `data[].steps[].position` | integer | Yes | Its place in the sequence, from 0. |
| `data[].steps[].kind` | string | Yes | One of `text`, `wait` |
| `data[].steps[].wait_seconds` | integer or null | Yes | For a wait: how long, from a minute to a year. |
| `data[].steps[].text` | string or null | Yes | For a text: the words, with `{{variables}}`. |
| `data[].steps[].template_id` | string or null | Yes | For a text: the template it uses instead of `text`. |
| `data[].steps[].service` | string | Yes | One of `auto`, `imessage`, `sms` |
| `data[].counts` | map of integer | Yes | Enrollments by state: `active`, `completed`, `stopped`, `canceled`. |
| `data[].created_via` | string | Yes | One of `dashboard`, `api`, `assistant`, `mcp`, `zapier`, `cli` |
| `data[].created_at` | timestamp | Yes | When it was made. |
| `has_more` | boolean | Yes | Whether another page follows. |
| `next_cursor` | string or null | Yes | Send as `cursor` for the next page; null on the last. |

The answer, `200`:

```json
{
  "object": "list",
  "data": [
    {
      "id": "seq_1Hq2LxW9cVbN3mKpRtYs0a",
      "object": "sequence",
      "name": "New lead follow-up",
      "description": "For people who ask about a listing.",
      "state": "active",
      "stop_on_reply": true,
      "send_window": {
        "days": [
          "mon",
          "tue",
          "wed",
          "thu",
          "fri"
        ],
        "start": "09:00",
        "end": "18:00"
      },
      "steps": [
        {
          "id": "step_1Hq2LxW9cVbN3mKpRtYs0a",
          "position": 0,
          "kind": "text",
          "wait_seconds": null,
          "text": "Hi {{first_name|there}}, thanks for asking about {{listing}}. Want to see it?",
          "template_id": null,
          "service": "auto"
        },
        {
          "id": "step_2Bf8QzD4kJmA6nXwEuTr1c",
          "position": 1,
          "kind": "wait",
          "wait_seconds": 172800,
          "text": null,
          "template_id": null,
          "service": "auto"
        },
        {
          "id": "step_3Lp3VsC7hGqE5tZyKbWn2d",
          "position": 2,
          "kind": "text",
          "wait_seconds": null,
          "text": "Just checking in. Still interested in {{listing}}?",
          "template_id": null,
          "service": "auto"
        }
      ],
      "counts": {
        "active": 12,
        "completed": 30,
        "stopped": 9,
        "canceled": 1
      },
      "created_via": "dashboard",
      "created_at": "2026-11-01T15:00:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

Every refusal has the same envelope and a page of its own. These are the ones this operation can give.

| Code                                                    | Status | What it means                                                                                                                                    |
| ------------------------------------------------------- | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| [`unauthorized`](https://usebluebot.com/docs/errors/unauthorized)             | 401    | The request carried no key, or a key BlueBot doesn’t know: mistyped, revoked, or a test key sent to the live API.                                |
| [`insufficient_scope`](https://usebluebot.com/docs/errors/insufficient_scope) | 403    | The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope.                                                   |
| [`rate_limited`](https://usebluebot.com/docs/errors/rate_limited)             | 429    | Too many requests. A key may make 120 requests a minute. The `RateLimit` header says how many are left, and `Retry-After` how long to wait.      |
| [`internal`](https://usebluebot.com/docs/errors/internal)                     | 500    | Something went wrong on BlueBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe.                    |
| [`invalid_request`](https://usebluebot.com/docs/errors/invalid_request)       | 400    | Something in the request doesn’t fit: a missing or malformed field, a bad id, or a combination the endpoint refuses. `details` names each field. |

## Try it