> For the complete documentation index, see [llms.txt](https://developers.oxylabs.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/scheduler.md).

# Scheduler

Automatize tarefas recorrentes de scraping com o Scheduler gratuito na Web Scraper API. Defina a frequência com cron, especifique itens da tarefa e horário de término, e monitore execuções por meio de endpoints dedicados.

[**Scheduler**](https://oxylabs.io/features/scheduler) é um **recurso gratuito** do Web Scraper API que permite automatizar trabalhos recorrentes de scraping e parsing criando agendamentos.

Confira o tutorial em vídeo abaixo para saber mais sobre o Scheduler e como ele funciona.

{% embed url="<https://www.youtube.com/watch?v=HJLkFZ_9Z5w>" %}
Guia passo a passo para automatizar suas tarefas recorrentes de scraping usando o Scheduler
{% endembed %}

Aconselhamos usar o Scheduler junto com o [**Upload para Cloud Storage**](/products/pt-br/web-scraper-api/features/result-processing-and-storage/cloud-storage.md) recurso. Dessa forma, você pode configurar seu agendamento e receber atualizações regulares de dados no seu armazenamento sem precisar buscar resultados no nosso sistema.

{% hint style="warning" %}
**IMPORTANTE**: O Scheduler é uma ferramenta poderosa que pode aumentar rapidamente sua conta de serviço. Aconselhamos testá-lo com alguns itens de trabalho e um número limitado de repetições para garantir que você obtenha os dados corretos nos intervalos certos. Depois que isso estiver estabelecido, você pode parar o agendamento de teste e criar um novo agendamento em maior escala.
{% endhint %}

## Início rápido

Ao criar um novo agendamento, siga os passos simples abaixo.

1. Diga-nos **com que frequência devemos repetir as tarefas** enviando uma expressão cron de agendamento;
2. Dê-nos **vários conjuntos de parâmetros de tarefa** que devemos executar nos horários agendados;
3. Informe-nos **quando parar** enviando um horário final.

Veja [**aqui**](#create-a-new-schedule) para encontrar um exemplo de código para enviar um novo agendamento.

{% hint style="info" %}
**OBS**: Você também pode baixar e importar [**esta coleção do Postman**](https://files.gitbook.com/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FiwDdoZGfMbUe5cRL2417%2Fuploads%2FsipIxRVxZmZroadwSuqg%2FScheduler.postman_collection.json?alt=media\&token=dac92525-e5cc-43c2-a8eb-a32e8eba0483) para experimentar todos os nossos endpoints do Scheduler. Novo no Postman? Saiba mais sobre esta ferramenta [**aqui**](/integrations/pt-br/web-scraper-api-integrations/postman.md).
{% endhint %}

## Endpoints

O Scheduler tem vários endpoints que você pode usar para controlar o serviço:

* [**Criar um novo agendamento**](#1.-create-a-new-schedule)
* [**Obter todos os agendamentos**](#get-all-schedules)
* [**Obter** **execuções** **informações**](#get-runs-information)
* [**Obter jobs agendados**](#get-scheduled-jobs)
* [**Obter informações do agendamento**](#get-schedule-info)
* [**Desativar ou reativar um agendamento**](#change-schedule-state)

### Criar um novo agendamento

#### Visão geral

Use este endpoint para iniciar um novo agendamento.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules`
* **Método**: `POST`
* **Autenticação**: `Basic`
* **Cabeçalhos da requisição**: `Content-Type: application/json`

**Entrada**

<table><thead><tr><th width="125">Parâmetro</th><th width="477.3333333333333">Descrição</th><th>Valor padrão</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><strong><code>cron</code></strong></mark></td><td>Expressão de agendamento cron. Ela determina com que frequência o agendamento enviado será executado. Leia mais <a href="https://crontab.guru/"><strong>aqui</strong></a> e <a href="https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm"><strong>aqui</strong></a>.</td><td>-</td></tr><tr><td><mark style="background-color:green;"><strong><code>itens</code></strong></mark></td><td>Lista de conjuntos de parâmetros de tarefa da Scraper API que devem ser executados como parte do agendamento.</td><td>-</td></tr><tr><td><mark style="background-color:green;"><strong><code>end_time</code></strong></mark></td><td>O momento em que o agendamento deve parar de ser executado. Obs.: o horário final é inclusivo.</td><td>-</td></tr></tbody></table>

\- parâmetro obrigatório

{% hint style="info" %}
**OBS**: Para orientação sobre como montar conjuntos de parâmetros de job para a **`itens`** parte do seu payload do Scheduler, consulte a página de documentação do scraper específico que você deseja usar (por exemplo, [**Google**](/api-targets/pt-br/search-engines/google.md), [**Amazon**](/api-targets/pt-br/e-commerce/amazon.md), etc.).
{% endhint %}

O payload abaixo fará o Scheduler executar dois jobs às 03:00 às segundas-feiras até `end_time` (inclusive).

```json
{
  "cron": "0 3 * * 1",
  "items": [
    {"source": "universal", "url": "https://ip.oxylabs.io"},
    {"source": "google_search", "query": "stuff"}
  ],
  "end_time": "2032-12-21 12:34:45"
}
```

#### Saída

A resposta abaixo confirma que o agendamento foi criado com sucesso. Ela inclui `items_count` (o número de conjuntos de parâmetros de job que você enviou), o horário da primeira execução e links para os `execuções` e `jobs` do novo agendamento.

```json
{
    "schedule_id": 168110763619310929,
    "active": true,
    "items_count": 2,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2026-09-21 03:00:00",
    "links": [
        {
            "rel": "runs",
            "href": "/v1/schedules/168110763619310929/runs",
            "method": "GET"
        },
        {
            "rel": "jobs",
            "href": "/v1/schedules/168110763619310929/jobs",
            "method": "GET"
        }
    ]
}
```

### Obter todos os agendamentos

#### Visão geral

Use este endpoint para obter a lista de todos os agendamentos associados à sua conta de usuário.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

Este endpoint retorna a lista de todos os IDs de agendamento associados à conta de usuário que faz a solicitação.

Veja a resposta de exemplo abaixo. Os IDs dos agendamentos são retornados como cadeias de caracteres.

```json
{
    "schedules": [
        "168110763619310929",
        "195963006349271396",
        "1192925426751182410",
        "2482057452528425703"
    ]
}
```

### Obter informações das execuções

#### Visão geral

Use este endpoint para obter informações sobre uma lista de todas as execuções em um agendamento, com os metadados de cada job e a taxa de sucesso de cada execução.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/runs`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

O payload abaixo contém uma resposta de exemplo `/runs` do endpoint.

```json
{
    "runs": [
        {
            "run_id": 105302280,
            "jobs": [
                {
                    "id": 7505291047442843649,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2026-09-14 15:47:07",
                    "result_created_at": "2026-09-14 15:47:09"
                }
            ],
            "success_rate": 1.0
        },
        {
            "run_id": 105302283,
            "jobs": [
                {
                    "id": 7505291294688676865,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2026-09-14 15:48:06",
                    "result_created_at": "2026-09-14 15:48:07"
                }
            ],
            "success_rate": 1.0
        }
    ]
}
```

<table><thead><tr><th width="216">Chave</th><th>Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>execuções</code></td><td>Uma coleção de objetos de execução que representam instâncias de execução de uma tarefa ou fluxo de trabalho agendado.</td><td>Vetor</td></tr><tr><td><code>execuções</code>:<code>run_id</code></td><td>Um identificador único para a instância específica da execução.</td><td>Inteiro</td></tr><tr><td><code>execuções</code>:<code>jobs</code></td><td>Uma coleção de objetos de job que foram executados como parte desta execução.</td><td>Vetor</td></tr><tr><td><code>execuções</code>:<code>success_rate</code></td><td>A razão entre o número de jobs bem-sucedidos e o total de jobs nesta execução (varia de 0 a 1).</td><td>Número</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>id</code></td><td>Um identificador exclusivo da Oxylabs para o job específico.</td><td>Inteiro</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>create_status_code</code></td><td>Código de status HTTP retornado quando o job foi criado, indicando a aceitação inicial da solicitação de job.</td><td>Inteiro</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>result_status</code></td><td>O status de execução do job: <code>pending</code>, <code>done</code> ou <code>faulted</code>.</td><td>Texto</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>created_at</code></td><td>Carimbo de data/hora em que o job foi criado</td><td>Texto</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>result_created_at</code></td><td>Carimbo de data/hora em que o job foi concluído e produziu um resultado</td><td>Texto</td></tr></tbody></table>

### Obter jobs agendados

#### Visão geral

Use este endpoint para obter a lista de jobs de scraping executados como resultado da execução de um agendamento.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/jobs`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

O payload abaixo contém uma resposta de exemplo: os IDs de todos os jobs criados pelo agendamento até agora.

```json
{
    "jobs": [
        7505291047442843649,
        7505291294688676865
    ]
}
```

### Obter informações do agendamento

#### Visão geral

Use este endpoint para obter informações sobre um agendamento específico.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}`
* **Método**: `GET`
* **Autenticação**: `Basic`

#### Saída

O payload abaixo contém uma resposta de exemplo com as informações do agendamento. Antes da primeira execução, `stats` é um objeto vazio.

```json
{
    "schedule_id": 485005153871537982,
    "active": true,
    "items_count": 2,
    "cron": "26 8 * * *",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2026-09-16 08:26:00",
    "links": [
        {
            "rel": "runs",
            "href": "/v1/schedules/485005153871537982/runs",
            "method": "GET"
        },
        {
            "rel": "jobs",
            "href": "/v1/schedules/485005153871537982/jobs",
            "method": "GET"
        }
    ],
    "stats": {
        "total_job_count": 2,
        "job_create_outcomes": [
            {
                "status_code": 202,
                "job_count": 2,
                "ratio": 1.0
            }
        ],
        "job_result_outcomes": [
            {
                "status": "done",
                "job_count": 2,
                "ratio": 1.0
            }
        ]
    }
}
```

<table><thead><tr><th width="239.58203125">Chave</th><th width="395.515625">Descrição</th><th>Tipo</th></tr></thead><tbody><tr><td><code>schedule_id</code></td><td>O ID exclusivo do agendamento.</td><td>Inteiro</td></tr><tr><td><code>active</code></td><td>O agendamento está ativo no momento?</td><td>Booleano</td></tr><tr><td><code>items_count</code></td><td>O número de itens (jobs) no agendamento.</td><td>Inteiro</td></tr><tr><td><code>cron</code></td><td>A expressão cron associada ao agendamento.</td><td>Texto</td></tr><tr><td><code>end_time</code></td><td>O momento em que o agendamento deixará de ser repetido.</td><td>Texto</td></tr><tr><td><code>next_run_at</code></td><td>O momento em que o agendamento será executado na próxima vez.</td><td>Texto</td></tr><tr><td><code>links</code></td><td>Uma coleção de objetos de link que define endpoints de API disponíveis relacionados a um recurso de agendamento.</td><td>Vetor</td></tr><tr><td><code>links</code>:<code>rel</code></td><td>O identificador da relação que explica a finalidade do link em relação ao recurso pai.</td><td>Texto</td></tr><tr><td><code>links</code>:<code>href</code></td><td>O caminho da URL para o endpoint da API. Representa a localização do recurso que pode ser acessado.</td><td>Texto</td></tr><tr><td><code>links</code>:<code>method</code></td><td>O método HTTP a ser usado ao acessar este endpoint.</td><td>Texto</td></tr><tr><td><code>stats</code></td><td>Contém estatísticas de criação e conclusão de jobs.</td><td>Objeto JSON</td></tr><tr><td><code>stats</code>:<code>total_job_count</code></td><td>O número total de jobs criados pelo agendamento até agora (em todas as execuções).</td><td>Inteiro</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code></td><td>Contém estatísticas de criação de jobs.</td><td>Vetor JSON</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>status_code</code></td><td>O código de status recebido em resposta a uma tentativa de executar o agendamento (criar um job de scraping/parsing).</td><td>Inteiro</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>job_count</code></td><td>O número de tentativas de criação de job que resultaram nesse código de status específico.</td><td>Inteiro</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>ratio</code></td><td>A razão entre o número de tentativas de criação de job que resultaram nessa tentativa específica e o número total de tentativas de criação de job.</td><td>Ponto flutuante</td></tr><tr><td><code>stats: job_result_outcomes</code></td><td>Contém as estatísticas de resultado de jobs de scraping/parsing executados como parte do agendamento.</td><td>Vetor JSON</td></tr><tr><td><code>stats : job_result_outcomes : status</code></td><td>O status do job. Valores possíveis: <code>pending</code> (o job ainda está sendo processado), <code>done</code> (o job foi concluído com sucesso), <code>faulted</code> (o job falhou).</td><td>Texto</td></tr><tr><td><code>job_count</code></td><td>O número de jobs que resultaram nesse determinado <code>status</code>.</td><td>Inteiro</td></tr><tr><td><code>stats : job_result_outcomes : ratio</code></td><td>A razão entre o número de jobs com esse status específico e o número total de jobs criados.</td><td>Ponto flutuante</td></tr></tbody></table>

### Desativar ou reativar um agendamento

#### Visão geral

Use este endpoint para ativar ou desativar um agendamento específico.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/state`
* **Método**: `PUT`
* **Autenticação**: `Basic`

#### Entrada

Use este endpoint para parar ou reiniciar um agendamento.

Ao definir `active` como `false`, você pode interromper a execução de um agendamento específico.

Se você definir `active` como `true`, você pode reativar um agendamento interrompido anteriormente.

```json
{
  "active": false
}
```

**Saída**

```json
null
```

A resposta padrão é um corpo de resposta vazio com um `202` código de status.

## Códigos de resposta da API

Para códigos de resposta da API, consulte [**API**](/products/pt-br/web-scraper-api/response-codes.md#api) A solicitação de agendamento com um parâmetro ausente ou inválido é rejeitada com HTTP `422` e uma `lista de detalhes` um ID de agendamento desconhecido retorna HTTP `404`.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.oxylabs.io/products/pt-br/web-scraper-api/features/scheduler.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.