API задач

API для получения информации о задачах и статистике в системе Revo. Задачи создаются для ключевых слов проектов и отправляются в очередь на выполнение.

Структура задачи

Поле	Тип	Описание
id	integer	Уникальный идентификатор задачи
user_id	integer	ID пользователя, создавшего задачу
project_id	integer	ID проекта, к которому относится задача
keyword	string	Ключевое слово для поиска
domain	string	Домен сайта, для которого выполняется задача
click_count	integer	Общее количество кликов для задачи
remaining_clicks	integer	Оставшееся количество кликов
region	integer	Идентификатор региона для поиска
brand	string	Бренд (если указан)
node	string	Идентификатор узла обработки
status	string	Статус задачи (pending, in_progress, completed, canceled, not_found, error)
created_at	datetime	Дата создания
updated_at	datetime	Дата обновления

Получение списка задач

GET /api/v1/tasks?limit=50&offset=0

Параметры запроса

Параметр	Тип	Обязательный	Описание
limit	integer	Нет	Количество задач в ответе (по умолчанию 50)
offset	integer	Нет	Смещение для пагинации (по умолчанию 0)
status	string/array	Нет	Фильтр по статусу задачи (pending, in_progress, completed, canceled, not_found, error)
keyword	string	Нет	Фильтр по ключевому слову (частичное совпадение)
domain	string	Нет	Фильтр по домену (частичное совпадение)
period	string	Нет	Предустановленный период (today, yesterday, week, month, quarter, year) или количество дней назад
date_from	date	Нет	Начальная дата для фильтрации (YYYY-MM-DD)
date_to	date	Нет	Конечная дата для фильтрации (YYYY-MM-DD)
min_clicks	integer	Нет	Минимальное количество кликов
max_clicks	integer	Нет	Максимальное количество кликов
region	integer	Нет	Фильтр по региону
node	string	Нет	Фильтр по узлу обработки
sort_field	string	Нет	Поле для сортировки (по умолчанию created_at)
sort_direction	string	Нет	Направление сортировки (asc или desc, по умолчанию desc)

Пример ответа

{
    "error": "",
    "result": [
        {
            "id": 1,
            "user_id": 1,
            "project_id": 1,
            "keyword": "купить мебель в москве",
            "domain": "mebel-shop.ru",
            "click_count": 5,
            "remaining_clicks": 3,
            "region": 213,
            "brand": null,
            "node": "default",
            "status": "in_progress",
            "created_at": "2025-01-01T00:00:00.000000Z",
            "updated_at": "2025-01-01T01:00:00.000000Z"
        }
    ],
    "total": 1
}

Получение списка задач для проекта

GET /api/v1/project/{projectId}/tasks?limit=50&offset=0

Параметры запроса

Аналогичны параметрам запроса списка всех задач.

Пример ответа

Аналогичен ответу на запрос списка всех задач.

Получение данных конкретной задачи

GET /api/v1/task/{id}

Параметры запроса

Параметр	Тип	Обязательный	Описание
id	integer	Да	ID задачи (в URL)

Пример ответа

{
    "error": "",
    "result": {
        "id": 1,
        "user_id": 1,
        "project_id": 1,
        "keyword": "купить мебель в москве",
        "domain": "mebel-shop.ru",
        "click_count": 5,
        "remaining_clicks": 3,
        "region": 213,
        "brand": null,
        "node": "default",
        "status": "in_progress",
        "created_at": "2025-01-01T00:00:00.000000Z",
        "updated_at": "2025-01-01T01:00:00.000000Z"
    }
}

Получение статистики задач

GET /api/v1/tasks/statistics

Параметры запроса

Параметр	Тип	Обязательный	Описание
period	string	Нет	Предустановленный период (today, yesterday, week, month, quarter, year) или количество дней назад
date_from	date	Нет	Начальная дата для фильтрации (YYYY-MM-DD)
date_to	date	Нет	Конечная дата для фильтрации (YYYY-MM-DD)
status	string/array	Нет	Фильтр по статусу задачи (pending, in_progress, completed, canceled, not_found, error)
domain	string	Нет	Фильтр по домену (частичное совпадение)
keyword	string	Нет	Фильтр по ключевому слову (частичное совпадение)

Пример ответа

{
    "error": "",
    "result": {
        "all": {
            "total": 100,
            "by_status": {
                "completed": 50,
                "pending": 20,
                "in_progress": 15,
                "canceled": 10,
                "not_found": 3,
                "error": 2
            },
            "clicks": {
                "total": 500,
                "remaining": 150,
                "used": 350
            },
            "by_date": [
                {
                    "date": "2025-01-10",
                    "count": 15
                },
                {
                    "date": "2025-01-09",
                    "count": 22
                }
            ],
            "top_domains": [
                {
                    "domain": "example.com",
                    "count": 30
                },
                {
                    "domain": "test-site.ru",
                    "count": 25
                }
            ],
            "top_keywords": [
                {
                    "keyword": "купить ноутбук",
                    "count": 15
                },
                {
                    "keyword": "заказать пиццу",
                    "count": 12
                }
            ]
        },
        "filtered": {
            "total": 35,
            "by_status": {
                "completed": 20,
                "pending": 8,
                "in_progress": 5,
                "canceled": 2,
                "not_found": 0,
                "error": 0
            },
            "clicks": {
                "total": 175,
                "remaining": 50,
                "used": 125
            },
            "by_date": [
                {
                    "date": "2025-01-10",
                    "count": 7
                },
                {
                    "date": "2025-01-09",
                    "count": 12
                }
            ],
            "top_domains": [
                {
                    "domain": "example.com",
                    "count": 15
                },
                {
                    "domain": "test-site.ru",
                    "count": 10
                }
            ],
            "top_keywords": [
                {
                    "keyword": "купить ноутбук",
                    "count": 8
                },
                {
                    "keyword": "заказать пиццу",
                    "count": 6
                }
            ]
        }
    }
}

Получение статистики задач для проекта

GET /api/v1/project/{projectId}/tasks/statistics

Параметры запроса

Аналогичны параметрам запроса общей статистики задач.

Пример ответа

{
    "error": "",
    "result": {
        "all": {
            "total": 50,
            "by_status": {
                "completed": 30,
                "pending": 10,
                "in_progress": 5,
                "canceled": 3,
                "not_found": 1,
                "error": 1
            },
            "clicks": {
                "total": 250,
                "remaining": 75,
                "used": 175
            },
            "by_date": [
                {
                    "date": "2025-01-10",
                    "count": 8
                },
                {
                    "date": "2025-01-09",
                    "count": 12
                }
            ],
            "top_domains": [
                {
                    "domain": "example.com",
                    "count": 50
                }
            ],
            "top_keywords": [
                {
                    "keyword": "купить ноутбук",
                    "count": 10
                },
                {
                    "keyword": "заказать пиццу",
                    "count": 8
                }
            ]
        },
        "filtered": {
            "total": 20,
            "by_status": {
                "completed": 15,
                "pending": 3,
                "in_progress": 2,
                "canceled": 0,
                "not_found": 0,
                "error": 0
            },
            "clicks": {
                "total": 100,
                "remaining": 30,
                "used": 70
            },
            "by_date": [
                {
                    "date": "2025-01-10",
                    "count": 4
                },
                {
                    "date": "2025-01-09",
                    "count": 7
                }
            ],
            "top_domains": [
                {
                    "domain": "example.com",
                    "count": 20
                }
            ],
            "top_keywords": [
                {
                    "keyword": "купить ноутбук",
                    "count": 5
                },
                {
                    "keyword": "заказать пиццу",
                    "count": 4
                }
            ]
        },
        "project": {
            "id": 1,
            "name": "Мой проект",
            "domain": "example.com"
        }
    }
}

Получение информации о очереди задач

GET /api/v1/tasks/queue-status

Параметры запроса

Параметр	Тип	Обязательный	Описание
project_id	integer	Нет	Фильтр по ID проекта

Пример ответа

{
    "error": "",
    "result": {
        "user_pending": 25,
        "user_in_progress": 10,
        "system_pending_total": 150,
        "estimated_wait_time": {
            "minutes": 10,
            "formatted": "10 мин."
        }
    }
}

Статусы задач

Статус	Описание
pending	Задача в очереди на выполнение
in_progress	Задача выполняется
completed	Задача успешно выполнена
cancel	Задача отменена
not_found	Сайт не найден в поисковой выдаче
error	Ошибка при выполнении задачи

Дополнительная информация

Фильтрация по датам

API поддерживает несколько вариантов фильтрации задач по датам:

1. Предустановленные периоды:

   • today - задачи за сегодня
   • yesterday - задачи за вчера
   • week - задачи за текущую неделю
   • month - задачи за текущий месяц
   • quarter - задачи за текущий квартал
   • year - задачи за текущий год

2. Произвольный период в днях:

   • Если в параметре period указано числовое значение (например, 7), будут возвращены задачи за последние 7 дней

3. Точный диапазон дат:

   • date_from - начальная дата (включительно)
   • date_to - конечная дата (включительно)

Статистика

Статистика по задачам включает:

1. Общую информацию:

   • Общее количество задач
   • Количество задач по каждому статусу

2. Статистику по кликам:

   • Общее количество кликов
   • Оставшееся количество кликов
   • Использованное количество кликов

3. Распределение по датам:

   • Группировка задач по дням создания

4. Популярные домены и ключевые слова:

   • Топ-5 доменов по количеству задач
   • Топ-5 ключевых слов по количеству задач

Оценка времени ожидания

Система автоматически рассчитывает примерное время ожидания выполнения задач на основе:

• Количества задач пользователя в очереди
• Количества активных узлов обработки
• Среднего времени обработки одной задачи

Примерное время ожидания предоставляется в минутах и в форматированном виде (часы и минуты для больших значений).