# Scheduler

[**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 to 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 tentar buscar resultados do nosso sistema.

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

## Início Rápido

Ao criar um novo agendamento, siga as etapas simples abaixo.

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

&#x20;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**](broken://spaces/0ejViy9b0hpEq5P8gbMb/pages/d4243dc2129737ba75887447d05c21bbd9b0e017).
{% endhint %}

## Endpoints

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

* [**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 tarefas agendadas**](#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="color:padrão;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="color:padrão;background-color:green;"><strong><code>itens</code></strong></mark></td><td>Lista de conjuntos de parâmetros de tarefa do Scraper API que devem ser executados como parte do agendamento.</td><td>-</td></tr><tr><td><mark style="color:padrão;background-color:green;"><strong><code>end_time</code></strong></mark></td><td>O horário em que o agendamento deve parar de ser executado. OBS.: o horário de término é inclusivo.</td><td>-</td></tr></tbody></table>

&#x20;    \- parâmetro obrigatório

{% hint style="info" %}
**OBSERVAÇÃO**: Para orientações sobre como montar conjuntos de parâmetros de tarefa 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/mecanismos-de-busca/google.md), [**Amazon**](/api-targets/pt-br/e-commerce/amazon.md), etc.).
{% endhint %}

O payload abaixo fará o Scheduler executar duas tarefas agendadas às 03:00 nas 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.

```json
{
    "schedule_id": 4134906379157007223,
    "active": true,
    "items_count": 3,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2022-06-06 10:15:00"
}
```

### 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.

```json
{
    "schedules": [
        1764178033254455101,
        2885262175311057587,
        3251365810325795747,
        4134906379157007223,
        4164931482277157062
    ]
}
```

### 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 tarefa 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 do endpoint `/runs` .

```javascript
{
 "runs": [
        {
            "run_id": 25037485,
            "jobs": [
                {
                    "id": 7300439540206948353,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:23"
                },
                {
                    "id": 7300439540169188353,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:22"
                },
                {
                    "id": 7300439540198551553,
                    "create_status_code": 202,
                    "result_status": "done",
                    "created_at": "2025-02-26 09:00:21",
                    "result_created_at": "2025-02-26 09:00:23"
                }
            ],
            "success_rate": 1
        }
}
```

<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 tarefa 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 proporção de tarefas bem-sucedidas em relação ao total de tarefas 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 a tarefa específica.</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 a tarefa foi criada, indicando a aceitação inicial da solicitação da tarefa.</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 da tarefa (por exemplo, "done", "failed", "pending").</td><td>String</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>created_at</code></td><td>Carimbo de data/hora em que a tarefa foi criada</td><td>String</td></tr><tr><td><code>execuções</code>:<code>jobs</code>:<code>result_created_at</code></td><td>Carimbo de data/hora em que a tarefa foi concluída e produziu um resultado</td><td>String</td></tr></tbody></table>

### Obter tarefas agendadas

#### Visão geral

Use este endpoint para obter a lista de tarefas de scraping executadas como resultado da execução de um agendamento.&#x20;

* **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 de informações do agendamento.

```json
{
    "jobs": [
        7300439540206948353,
        7300439540169188353,
        7300439540198551553,
        ...,
      ]
}
```

### Obter informações do agendamento

#### Visão geral

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

* **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.

<pre class="language-json"><code class="lang-json">{
    "schedule_id": 1764178033254455101,
    "active": true,
    "items_count": 3,
    "cron": "0 3 * * 1",
    "end_time": "2032-12-21 12:34:45",
    "next_run_at": "2022-06-06 10:18:00",
<strong>    "links": [
</strong>        {
            "rel": "runs",
            "href": "/v1/schedules/1764178033254455101/runs",
            "method": "GET"
        },
        {
            "rel": "jobs",
            "href": "/v1/schedules/1764178033254455101/jobs",
            "method": "GET"
        }
    ],
    "stats": {
        "total_job_count": 3,
        "job_create_outcomes": [
            {
                "status_code": 202,
                "job_count": 3,
                "ratio": 1
            }
        ],
        "job_result_outcomes": [
            {
                "status": "done",
                "job_count": 2,
                "ratio": 0.67
            },
            {
                "status": "faulted",
                "job_count": 1,
                "ratio": 0.33
            }
        ]
    }
}
</code></pre>

<table><thead><tr><th width="216">Chave</th><th>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 agora?</td><td>Booleano</td></tr><tr><td><code>items_count</code></td><td>O número de itens (tarefas) no agendamento.</td><td>Inteiro</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 horário até o qual o agendamento deixará de ser repetido.</td><td>String</td></tr><tr><td><code>next_run_at</code></td><td>O horário em que o agendamento será executado da próxima vez.</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>Vetor</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 da 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 tarefas.</td><td>Objeto JSON</td></tr><tr><td><code>stats</code>:<code>total_job_count</code></td><td>O número de itens (tarefas) no agendamento.</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 tarefas.</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 uma tarefa 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 tarefas 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 proporção entre o número de tentativas de criação de tarefas que resultaram nessa tentativa específica e o número total de tentativas de criação de tarefas.</td><td>Float</td></tr><tr><td><code>job_result_outcomes</code></td><td>Contém as estatísticas de resultado das tarefas de scraping/parsing executadas como parte do agendamento.</td><td>Array JSON</td></tr><tr><td><code>status</code></td><td>O status da tarefa. Valores possíveis: <code>pending</code> (a tarefa ainda está sendo processada), <code>done</code> (a tarefa foi concluída com sucesso), <code>faulted</code> (a tarefa falhou).</td><td>String</td></tr><tr><td><code>job_count</code></td><td>O número de tarefas que resultaram nesse particular <code>status</code>.</td><td>Inteiro</td></tr><tr><td><code>ratio</code></td><td>A proporção entre o número de tarefas com esse status específico e o número total de tarefas criadas.</td><td>Float</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 parar ou reiniciar um agendamento.&#x20;

Ao definir `active` até `false`, você pode interromper a execução de um agendamento específico.&#x20;

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

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

**Saída**

```json
nulo
```

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) .


---

# Agent Instructions: 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:

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

The question should be specific, self-contained, and written in natural language.
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.