> 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 jobs de scraping recorrentes com o Scheduler gratuito na Web Scraper API. Defina a frequência com cron, especifique itens do job e horário de término, e monitore as execuções por meio de endpoints dedicados.

[**Scheduler**](https://oxylabs.io/features/scheduler) é um **recurso gratuito** do Web Scraper API que permite automatizar tarefas 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 %}

Recomendamos usar o Scheduler junto com o [**Upload para o Cloud Storage**](https://developers.oxylabs.io/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 tentar buscar resultados no nosso sistema.

{% hint style="warning" %}
**IMPORTANTE**: O Scheduler é uma ferramenta poderosa que pode aumentar rapidamente sua fatura do serviço. Recomendamos testá-lo com alguns itens de job 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 interromper o agendamento de teste e criar um novo agendamento ampliado.
{% endhint %}

## Início rápido

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

1. Informe-nos **com que frequência devemos repetir os jobs** enviando uma expressão de agendamento cron;
2. Forneça-nos **um conjunto de parâmetros de job** que devemos executar nos horários agendados;
3. Informe-nos **quando parar** enviando um horário de término.

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

{% hint style="info" %}
**OBSERVAÇÃO**: 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 testar todos os nossos endpoints do Scheduler. Novo no Postman? Saiba mais sobre esta ferramenta [**aqui**](https://developers.oxylabs.io/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**: `Básico`
* **Cabeçalhos da solicitaçã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 cron do agendamento. 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>items</code></strong></mark></td><td>Lista de conjuntos de parâmetros de job das Scraper APIs 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 de término é inclusivo.</td><td>-</td></tr></tbody></table>

\- parâmetro obrigatório

{% hint style="info" %}
**OBSERVAÇÃO**: Para orientações sobre como montar conjuntos de parâmetros de job para o **`items`** trecho do seu payload do Scheduler, consulte a página de documentação do scraper específico que você gostaria de usar (por exemplo, [**Google**](https://developers.oxylabs.io/api-targets/pt-br/search-engines/google), [**Amazon**](https://developers.oxylabs.io/api-targets/pt-br/e-commerce/amazon), 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` endpoints 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**: `Básico`

#### Saída

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

Veja a resposta de exemplo abaixo. Os IDs de agendamento são retornados como strings.

```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**: `Básico`

#### 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>Array</td></tr><tr><td><code>execuções</code>:<code>run_id</code></td><td>Um identificador exclusivo para a instância específica de execução.</td><td>Integer</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>Array</td></tr><tr><td><code>execuções</code>:<code>success_rate</code></td><td>A proporção de jobs bem-sucedidos em relação ao 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>Integer</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 do job.</td><td>Integer</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>pendente</code>, <code>concluído</code> or <code>faulted</code>.</td><td>String</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>created_at</code></td><td>Timestamp em que o job foi criado</td><td>String</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>result_created_at</code></td><td>Timestamp em que o job foi concluído e gerou um resultado</td><td>String</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**: `Básico`

#### 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**: `Básico`

#### Saída

O payload abaixo contém uma resposta de exemplo de 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>Integer</td></tr><tr><td><code>active</code></td><td>O agendamento está ativo agora?</td><td>Boolean</td></tr><tr><td><code>items_count</code></td><td>O número de itens (jobs) no agendamento.</td><td>Integer</td></tr><tr><td><code>cron</code></td><td>A expressão cron associada ao agendamento.</td><td>String</td></tr><tr><td><code>end_time</code></td><td>O momento em que o agendamento deixará de ser repetido.</td><td>String</td></tr><tr><td><code>next_run_at</code></td><td>O momento em que o agendamento será executado novamente.</td><td>String</td></tr><tr><td><code>links</code></td><td>Uma coleção de objetos de link que definem os endpoints de API disponíveis relacionados a um recurso de agendamento.</td><td>Array</td></tr><tr><td><code>links</code>:<code>rel</code></td><td>O identificador de relacionamento que explica a finalidade do link em relação ao recurso pai.</td><td>String</td></tr><tr><td><code>links</code>:<code>href</code></td><td>O caminho de URL para o endpoint da API. Representa a localização do recurso que pode ser acessada.</td><td>String</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>String</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>Integer</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>Array 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>Integer</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>Integer</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>ratio</code></td><td>A proporçã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>Número decimal</td></tr><tr><td><code>stats: job_result_outcomes</code></td><td>Contém as estatísticas de resultado dos jobs de scraping/parsing executados como parte do agendamento.</td><td>Array JSON</td></tr><tr><td><code>stats : job_result_outcomes : status</code></td><td>O status do job. Valores possíveis: <code>pendente</code> (o job ainda está sendo processado), <code>concluído</code> (o job foi concluído com sucesso), <code>faulted</code> (o job falhou).</td><td>String</td></tr><tr><td><code>job_count</code></td><td>O número de jobs que resultaram nesse determinado <code>status</code>.</td><td>Integer</td></tr><tr><td><code>stats : job_result_outcomes : ratio</code></td><td>A proporção entre o número de jobs com esse status específico e o número total de jobs criados.</td><td>Número decimal</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**: `Básico`

#### Entrada

Use este endpoint para interromper ou reiniciar um agendamento.

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

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

```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**](https://developers.oxylabs.io/products/pt-br/web-scraper-api/response-codes.md#api) seção. Uma solicitação de agendamento com parâmetro ausente ou inválido é rejeitada com HTTP `422` e um `detail` lista nomeando o campo; 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
