# 03-PAGINATION.md - n8n REST API Pagination
**Версия API:** v1
**Дата документации:** 2025-12-25
**Источник:** Официальная документация n8n через Context7
---
## 📋 Содержание
1. [Введение](#введение)
2. [Cursor-Based Pagination](#cursor-based-pagination)
3. [Параметры пагинации](#параметры-пагинации)
4. [Структура ответа](#структура-ответа)
5. [Примеры использования](#примеры-использования)
6. [Best Practices](#best-practices)
7. [Troubleshooting](#troubleshooting)
---
## Введение
n8n REST API использует **cursor-based pagination** для эффективной работы с большими наборами данных. Пагинация позволяет разбивать результаты на управляемые страницы, снижая нагрузку на сервер и ускоряя время отклика API.
### Зачем нужна пагинация?
**Проблема без пагинации:**
- Получение всех workflows сразу может вернуть тысячи записей
- Большие ответы замедляют передачу данных
- Высокая нагрузка на память клиента и сервера
- Долгое время ожидания ответа
**Решение с пагинацией:**
- ✅ Контролируемый размер ответов
- ✅ Быстрые ответы API
- ✅ Меньшая нагрузка на память
- ✅ Возможность обработки данных по частям
- ✅ Лучшая производительность
### Endpoints с поддержкой пагинации
Следующие endpoints поддерживают пагинацию:
| Endpoint | Описание | Default Limit | Max Limit |
|----------|----------|---------------|-----------|
| `GET /api/v1/workflows` | Список workflows | 100 | 250 |
| `GET /api/v1/executions` | Список executions | 100 | 250 |
| `GET /api/v1/tags` | Список tags | 100 | 250 |
---
## Cursor-Based Pagination
### Принцип работы
n8n API использует **cursor-based pagination** вместо традиционной offset-based пагинации.
**Cursor-Based (используется в n8n):**
```
Page 1: GET /workflows?limit=100
Response: { data: [...], nextCursor: "ABC" }
Page 2: GET /workflows?limit=100&cursor=ABC
Response: { data: [...], nextCursor: "XYZ" }
Page 3: GET /workflows?limit=100&cursor=XYZ
Response: { data: [...] } // No nextCursor = last page
```
**Преимущества Cursor-Based:**
- ✅ Консистентные результаты при изменении данных
- ✅ Лучшая производительность для больших наборов данных
- ✅ Защита от пропуска или дублирования записей
- ✅ Эффективное использование индексов базы данных
**Offset-Based (НЕ используется в n8n):**
```
Page 1: GET /workflows?limit=100&offset=0
Page 2: GET /workflows?limit=100&offset=100
Page 3: GET /workflows?limit=100&offset=200
```
**Проблемы Offset-Based:**
- ❌ Дублирование/пропуск записей при изменении данных
- ❌ Медленная работа на больших offset
- ❌ Сложность поддержания консистентности
### Cursor Token
**Что такое cursor?**
- Непрозрачный строковый токен (opaque string token)
- Указывает на позицию в результатах
- Сгенерирован сервером, не должен модифицироваться клиентом
- Используется для получения следующей страницы
**Пример cursor:**
```
MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
```
**❌ НЕ делайте:**
- Не пытайтесь декодировать или модифицировать cursor
- Не создавайте собственные cursor значения
- Не сохраняйте cursor для длительного использования (они могут истечь)
**✅ Делайте:**
- Используйте cursor точно как получили от API
- Получайте новый cursor из каждого ответа
- Проверяйте наличие `nextCursor` для определения последней страницы
---
## Параметры пагинации
### Query Parameters
#### `limit` (integer, optional)
Количество результатов на одной странице.
**Формат:**
```
?limit=<number>
```
**Значения:**
- **Default:** 100
- **Minimum:** 1
- **Maximum:** 250
**Примеры:**
```bash
# Получить 50 workflows на странице
GET /api/v1/workflows?limit=50
# Получить максимальное количество (250)
GET /api/v1/workflows?limit=250
# Default (100) если не указан
GET /api/v1/workflows
```
#### `cursor` (string, optional)
Cursor токен для получения следующей страницы результатов.
**Формат:**
```
?cursor=<cursor-token>
```
**Получение cursor:**
- Извлекается из поля `nextCursor` предыдущего ответа
- Отсутствует в первом запросе (получаем первую страницу)
**Примеры:**
```bash
# Первая страница (без cursor)
GET /api/v1/workflows?limit=100
# Вторая страница (с cursor из первого ответа)
GET /api/v1/workflows?limit=100&cursor=MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA
# Третья страница (с cursor из второго ответа)
GET /api/v1/workflows?limit=100&cursor=NDU2ZGVmNzgtYWJjZC0xMmQzLWE0NTYtNzg5MDEyMzQ1Njc4
```
### Комбинирование параметров
Пагинация может комбинироваться с другими query параметрами:
```bash
# Активные workflows с пагинацией
GET /api/v1/workflows?active=true&limit=50&cursor=ABC
# Executions с фильтрацией и пагинацией
GET /api/v1/executions?status=error&workflowId=123&limit=100&cursor=XYZ
# Tags с пагинацией
GET /api/v1/tags?limit=25&cursor=DEF
```
---
## Структура ответа
### Response Format
Все paginated endpoints возвращают ответы в следующем формате:
```json
{
"data": [...], // Массив результатов
"nextCursor": "string" // Cursor для следующей страницы (optional)
}
```
### Поля ответа
#### `data` (array, required)
Массив объектов результатов для текущей страницы.
**Пример:**
```json
{
"data": [
{
"id": "1",
"name": "Workflow 1",
"active": true
},
{
"id": "2",
"name": "Workflow 2",
"active": false
}
]
}
```
#### `nextCursor` (string, optional)
Cursor токен для получения следующей страницы.
**Наличие поля:**
- ✅ **Присутствует:** Есть еще страницы данных
- ❌ **Отсутствует:** Это последняя страница
**Примеры:**
**Есть следующая страница:**
```json
{
"data": [...100 items...],
"nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}
```
**Последняя страница:**
```json
{
"data": [...50 items...]
// nextCursor отсутствует
}
```
---
## Примеры использования
### Пример 1: Basic Pagination (cURL)
**Первая страница:**
```bash
# n8n Cloud
curl -X GET \
'https://your-instance.app.n8n.cloud/api/v1/workflows?active=true&limit=150' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: your_api_key_here'
```
**Ответ:**
```json
{
"data": [
{
"id": "1",
"name": "Workflow 1",
"active": true
},
...150 workflows...
],
"nextCursor": "MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA"
}
```
**Вторая страница:**
```bash
curl -X GET \
'https://your-instance.app.n8n.cloud/api/v1/workflows?active=true&limit=150&cursor=MTIzZTQ1NjctZTg5Yi0xMmQzLWE0NTYtNDI2NjE0MTc0MDA' \
-H 'accept: application/json' \
-H 'X-N8N-API-KEY: your_api_key_here'
```
### Пример 2: Получить все workflows (JavaScript)
```javascript
const axios = require('axios');
const N8N_API_KEY = 'your_api_key_here';
const N8N_HOST = 'https://your-instance.app.n8n.cloud';
async function getAllWorkflows() {
const allWorkflows = [];
let cursor = null;
let hasMore = true;
while (hasMore) {
// Построить URL с параметрами
const params = {
limit: 250, // Максимальный размер страницы
...(cursor && { cursor }) // Добавить cursor если есть
};
try {
const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
params,
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
// Добавить результаты к общему массиву
allWorkflows.push(...response.data.data);
// Проверить наличие следующей страницы
if (response.data.nextCursor) {
cursor = response.data.nextCursor;
console.log(`Получено ${allWorkflows.length} workflows, загружаем еще...`);
} else {
hasMore = false;
console.log(`✅ Всего получено ${allWorkflows.length} workflows`);
}
} catch (error) {
console.error('Ошибка получения workflows:', error.message);
throw error;
}
}
return allWorkflows;
}
// Использование
getAllWorkflows()
.then(workflows => {
console.log(`Всего workflows: ${workflows.length}`);
workflows.forEach(workflow => {
console.log(`- ${workflow.name} (${workflow.id})`);
});
})
.catch(error => {
console.error('Ошибка:', error);
});
```
### Пример 3: Paginated Iteration (JavaScript)
```javascript
async function processWorkflowsInPages() {
let cursor = null;
let pageNumber = 1;
do {
const params = {
limit: 100,
...(cursor && { cursor })
};
const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
params,
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
// Обработать текущую страницу
console.log(`\n📄 Страница ${pageNumber}:`);
console.log(`Получено ${response.data.data.length} workflows`);
response.data.data.forEach((workflow, index) => {
console.log(` ${index + 1}. ${workflow.name} (Active: ${workflow.active})`);
});
// Подготовить следующую итерацию
cursor = response.data.nextCursor;
pageNumber++;
// Задержка между запросами (rate limiting)
if (cursor) {
await new Promise(resolve => setTimeout(resolve, 100));
}
} while (cursor);
console.log(`\n✅ Обработано ${pageNumber - 1} страниц`);
}
processWorkflowsInPages();
```
### Пример 4: Python Implementation
```python
import requests
from typing import List, Dict, Optional
N8N_API_KEY = 'your_api_key_here'
N8N_HOST = 'https://your-instance.app.n8n.cloud'
def get_all_workflows() -> List[Dict]:
"""Получить все workflows с пагинацией"""
all_workflows = []
cursor = None
has_more = True
while has_more:
# Построить параметры запроса
params = {'limit': 250}
if cursor:
params['cursor'] = cursor
try:
response = requests.get(
f'{N8N_HOST}/api/v1/workflows',
params=params,
headers={
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
)
response.raise_for_status()
data = response.json()
# Добавить результаты
all_workflows.extend(data['data'])
# Проверить следующую страницу
if 'nextCursor' in data:
cursor = data['nextCursor']
print(f'Получено {len(all_workflows)} workflows, загружаем еще...')
else:
has_more = False
print(f'✅ Всего получено {len(all_workflows)} workflows')
except requests.exceptions.RequestException as error:
print(f'Ошибка получения workflows: {error}')
raise
return all_workflows
# Использование
workflows = get_all_workflows()
print(f'\nВсего workflows: {len(workflows)}')
for workflow in workflows:
print(f"- {workflow['name']} ({workflow['id']})")
```
### Пример 5: Generator Pattern (Python)
```python
from typing import Iterator, Dict
def iterate_workflows(page_size: int = 100) -> Iterator[Dict]:
"""Generator для итерации по workflows постранично"""
cursor = None
while True:
params = {'limit': page_size}
if cursor:
params['cursor'] = cursor
response = requests.get(
f'{N8N_HOST}/api/v1/workflows',
params=params,
headers={
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
)
response.raise_for_status()
data = response.json()
# Yield каждый workflow
for workflow in data['data']:
yield workflow
# Проверить следующую страницу
if 'nextCursor' not in data:
break
cursor = data['nextCursor']
# Использование с generator
print('Активные workflows:')
for workflow in iterate_workflows(page_size=50):
if workflow['active']:
print(f"- {workflow['name']}")
```
### Пример 6: Async/Await (JavaScript)
```javascript
async function* paginatedWorkflows(pageSize = 100) {
let cursor = null;
do {
const params = {
limit: pageSize,
...(cursor && { cursor })
};
const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
params,
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
// Yield каждый workflow
for (const workflow of response.data.data) {
yield workflow;
}
cursor = response.data.nextCursor;
} while (cursor);
}
// Использование async generator
(async () => {
console.log('Активные workflows:');
for await (const workflow of paginatedWorkflows(50)) {
if (workflow.active) {
console.log(`- ${workflow.name}`);
}
}
})();
```
---
## Best Practices
### 1. Выбор размера страницы
**Рекомендации:**
```javascript
// ✅ Хорошо: Используйте разумные размеры страниц
const SMALL_PAGE = 50; // Для быстрых операций
const MEDIUM_PAGE = 100; // Default, оптимальный баланс
const LARGE_PAGE = 250; // Максимум, для bulk операций
// ❌ Плохо: Слишком маленькие или большие размеры
const TOO_SMALL = 1; // Слишком много запросов
const TOO_LARGE = 1000; // Превышает максимум (250)
```
**Когда использовать:**
- **50-100:** UI отображение, интерактивная работа
- **100-150:** Общие операции, хороший баланс
- **200-250:** Массовая обработка, экспорт данных
### 2. Error Handling
```javascript
async function safeGetAllWorkflows(maxRetries = 3) {
const allWorkflows = [];
let cursor = null;
let retries = 0;
do {
try {
const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
params: {
limit: 250,
...(cursor && { cursor })
},
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
allWorkflows.push(...response.data.data);
cursor = response.data.nextCursor;
retries = 0; // Reset retries на успешный запрос
} catch (error) {
if (error.response?.status === 429) {
// Rate limit - wait and retry
if (retries < maxRetries) {
retries++;
const delay = Math.pow(2, retries) * 1000; // Exponential backoff
console.log(`Rate limited, waiting ${delay}ms...`);
await new Promise(resolve => setTimeout(resolve, delay));
continue;
}
}
throw error;
}
} while (cursor);
return allWorkflows;
}
```
### 3. Progress Tracking
```javascript
async function getAllWorkflowsWithProgress() {
const allWorkflows = [];
let cursor = null;
let totalFetched = 0;
// Прогресс бар (опционально)
const startTime = Date.now();
do {
const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
params: {
limit: 250,
...(cursor && { cursor })
},
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
const pageSize = response.data.data.length;
totalFetched += pageSize;
allWorkflows.push(...response.data.data);
// Отображение прогресса
console.log(`📊 Получено: ${totalFetched} workflows${response.data.nextCursor ? ' (загружаем еще...)' : ''}`);
cursor = response.data.nextCursor;
} while (cursor);
const duration = ((Date.now() - startTime) / 1000).toFixed(2);
console.log(`✅ Завершено: ${totalFetched} workflows за ${duration}s`);
return allWorkflows;
}
```
### 4. Caching Strategies
```javascript
class WorkflowCache {
constructor(ttl = 5 * 60 * 1000) { // 5 minutes TTL
this.cache = null;
this.timestamp = null;
this.ttl = ttl;
}
async getAll() {
// Проверить cache
if (this.cache && Date.now() - this.timestamp < this.ttl) {
console.log('📦 Используем cached workflows');
return this.cache;
}
// Загрузить с пагинацией
console.log('🔄 Загружаем workflows...');
this.cache = await getAllWorkflows();
this.timestamp = Date.now();
return this.cache;
}
invalidate() {
this.cache = null;
this.timestamp = null;
}
}
// Использование
const workflowCache = new WorkflowCache();
const workflows = await workflowCache.getAll();
```
### 5. Rate Limiting
```javascript
class RateLimiter {
constructor(requestsPerSecond = 10) {
this.delay = 1000 / requestsPerSecond;
this.lastRequest = 0;
}
async throttle() {
const now = Date.now();
const timeSinceLastRequest = now - this.lastRequest;
if (timeSinceLastRequest < this.delay) {
await new Promise(resolve =>
setTimeout(resolve, this.delay - timeSinceLastRequest)
);
}
this.lastRequest = Date.now();
}
}
async function getAllWorkflowsWithRateLimit() {
const rateLimiter = new RateLimiter(5); // 5 requests/second
const allWorkflows = [];
let cursor = null;
do {
await rateLimiter.throttle();
const response = await axios.get(`${N8N_HOST}/api/v1/workflows`, {
params: {
limit: 250,
...(cursor && { cursor })
},
headers: {
'X-N8N-API-KEY': N8N_API_KEY,
'Accept': 'application/json'
}
});
allWorkflows.push(...response.data.data);
cursor = response.data.nextCursor;
} while (cursor);
return allWorkflows;
}
```
---
## Troubleshooting
### Проблема 1: Пустой ответ на первой странице
**Симптом:**
```json
{
"data": []
}
```
**Причины:**
- Нет данных соответствующих фильтрам
- Неверные параметры фильтрации
**Решение:**
```bash
# Проверьте без фильтров
GET /api/v1/workflows
# Проверьте с другими фильтрами
GET /api/v1/workflows?active=false
```
### Проблема 2: nextCursor всегда присутствует
**Симптом:**
Поле `nextCursor` присутствует даже на последней странице
**Причина:**
- Bug в API (очень редко)
**Решение:**
```javascript
// Защита от бесконечного цикла
const MAX_PAGES = 1000;
let pageCount = 0;
while (cursor && pageCount < MAX_PAGES) {
// fetch page
pageCount++;
}
if (pageCount >= MAX_PAGES) {
console.warn('Достигнут максимум страниц');
}
```
### Проблема 3: Cursor expired
**Симптом:**
```json
{
"error": "Invalid or expired cursor"
}
```
**Причина:**
- Cursor устарел (слишком долго между запросами)
- Cursor поврежден
**Решение:**
```javascript
// Начать с начала если cursor expired
try {
const response = await fetch(url);
// ...
} catch (error) {
if (error.message.includes('cursor')) {
console.log('Cursor expired, начинаем с начала');
cursor = null;
// retry
}
}
```
### Проблема 4: Дублирование данных
**Симптом:**
Одни и те же записи появляются на разных страницах
**Причина:**
- Изменение данных между запросами (очень редко с cursor-based)
**Решение:**
```javascript
// Дедупликация по ID
const seen = new Set();
const uniqueWorkflows = [];
for (const workflow of allWorkflows) {
if (!seen.has(workflow.id)) {
seen.add(workflow.id);
uniqueWorkflows.push(workflow);
}
}
```
---
## Связанные документы
- [01-OVERVIEW.md](./01-OVERVIEW.md) - Обзор n8n REST API
- [02-AUTHENTICATION.md](./02-AUTHENTICATION.md) - Аутентификация
- [10-WORKFLOWS-API.md](./10-WORKFLOWS-API.md) - Workflows API
- [20-EXECUTIONS-API.md](./20-EXECUTIONS-API.md) - Executions API
- [40-TAGS-API.md](./40-TAGS-API.md) - Tags API
---
**Последнее обновление:** 2025-12-25
**Версия документации:** 1.0
**Подготовлено:** James (Dev Agent) с использованием Context7 MCP Server
**Источники:**
- [n8n API Pagination Documentation](https://docs.n8n.io/api/pagination/)
