# Scheduler

[**Programador**](https://oxylabs.io/features/scheduler) es un **función gratuita** de Web Scraper API que te permite automatizar trabajos recurrentes de scraping y parsing creando cronogramas. 

Mira el tutorial en video abajo para aprender más sobre Scheduler y cómo funciona.

{% embed url="<https://www.youtube.com/watch?v=HJLkFZ_9Z5w>" %}
Guía paso a paso para automatizar tus trabajos recurrentes de scraping usando Scheduler
{% endembed %}

Recomendamos usar Scheduler junto con la [**Subida a Cloud Storage**](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/features/result-processing-and-storage/cloud-storage) característica. De este modo, puedes configurar tu programación y recibir actualizaciones de datos regulares en tu almacenamiento sin intentar recuperar resultados desde nuestro sistema.

{% hint style="warning" %}
**IMPORTANTE**: Scheduler es una herramienta potente que puede aumentar rápidamente tu factura de servicio. Recomendamos probarla con algunos elementos de trabajo y un número limitado de repeticiones para asegurarte de obtener los datos correctos en los intervalos adecuados. Una vez establecido eso, puedes detener la programación de prueba y crear una nueva programación ampliada.
{% endhint %}

## Inicio rápido

Al crear una nueva programación, sigue los pasos simples a continuación.

1. Dinos **con qué frecuencia debemos repetir los trabajos** enviando una expresión de cron;
2. Danos **un conjunto de parámetros de trabajo** que deberíamos ejecutar en los horarios programados;
3. Haznos saber **cuándo detenernos** enviando una hora de finalización.

&#x20;Consulta [**aquí**](#create-a-new-schedule) para encontrar un ejemplo de código para enviar una nueva programación.

{% hint style="info" %}
**NOTE**: También puedes descargar e importar [**esta colección de 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 probar todos nuestros endpoints de Scheduler. ¿Nuevo en Postman? Aprende más sobre esta herramienta [**aquí**](https://developers.oxylabs.io/documentation/es/guias-para-apis-de-scraper/using-postman).
{% endhint %}

## Endpoints

Scheduler tiene varios endpoints que puedes usar para controlar el servicio:&#x20;

* [**Crear una nueva programación**](#1.-create-a-new-schedule)
* [**Obtener todas las programaciones**](#get-all-schedules)
* [**Obtener** **ejecuciones** **información**](#get-runs-information)
* [**Obtener trabajos programados**](#get-scheduled-jobs)
* [**Obtener información de la programación**](#get-schedule-info)
* [**Desactivar o reactivar una programación**](#change-schedule-state)

### Crear una nueva programación

#### Descripción general

Usa este endpoint para iniciar una nueva programación.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules`
* **Método**: `POST`
* **Autenticación**: `Basic`
* **Encabezados de la solicitud**: `Content-Type: application/json`

**Entrada**

<table><thead><tr><th width="150">Parámetro</th><th width="435.3333333333333">Descripción</th><th>Valor predeterminado</th></tr></thead><tbody><tr><td> <mark style="color:predeterminado;background-color:green;"><strong><code>cron</code></strong></mark> </td><td>Expresión de cron. Determina con qué frecuencia se ejecutará la programación enviada. Lee más <a href="https://crontab.guru/"><strong>aquí</strong></a> y <a href="https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm"><strong>aquí</strong></a>.</td><td>-</td></tr><tr><td> <mark style="color:predeterminado;background-color:green;"><strong><code>elementos</code></strong></mark> </td><td>Lista de conjuntos de parámetros de trabajo de Scraper APIs que deben ejecutarse como parte de la programación.</td><td>-</td></tr><tr><td><mark style="color:predeterminado;background-color:green;"><strong><code>end_time</code></strong></mark> </td><td>La hora en la que la programación debe dejar de ejecutarse. NB: la hora de finalización es inclusiva.</td><td>-</td></tr></tbody></table>

&#x20;    \- parámetro requerido

{% hint style="info" %}
**NOTE**: Para obtener orientación sobre cómo confeccionar conjuntos de parámetros de trabajo para la **`elementos`** parte de tu payload de Scheduler, consulta la página de documentación del scraper particular que te gustaría usar (por ejemplo, [**Google**](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/targets/google), [**Amazon**](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/web-scraper-api/targets/amazon), etc.).
{% endhint %}

El payload abajo hará que Scheduler ejecute dos trabajos programados a las 03:00 los lunes hasta `end_time` (inclusive).

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

#### Salida

La respuesta abajo confirma que la programación se creó correctamente.

```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"
}
```

### Obtener todas las programaciones

#### Descripción general

Usa este endpoint para obtener la lista de todas las programaciones asociadas con tu cuenta de usuario.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules`
* **Método**: `GET`
* **Autenticación**: `Basic`

#### Salida

Este endpoint devuelve la lista de todos los IDs de programación asociados con la cuenta de usuario que realiza la solicitud.

Consulta la respuesta de ejemplo abajo.

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

### Obtener información de ejecuciones

#### Descripción general

Usa este endpoint para obtener información sobre la lista de todas las ejecuciones en una programación con los metadatos de cada trabajo y la tasa de éxito de cada ejecución.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/runs`
* **Método**: `GET`
* **Autenticación**: `Basic`

#### Salida

El payload abajo contiene una respuesta de ejemplo del `/runs` endpoint.

```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">Clave</th><th>Descripción</th><th>Tipo</th></tr></thead><tbody><tr><td><code>ejecuciones</code></td><td>Una colección de objetos run que representan instancias de ejecución de una tarea o flujo de trabajo programado.</td><td>Array</td></tr><tr><td><code>ejecuciones</code>:<code>run_id</code></td><td>Un identificador único para la instancia de ejecución específica.</td><td>Integer</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code></td><td>Una colección de objetos job que se ejecutaron como parte de esta ejecución.</td><td>Array</td></tr><tr><td><code>ejecuciones</code>:<code>success_rate</code></td><td>La proporción de trabajos exitosos respecto al total de trabajos en esta ejecución (rango de 0 a 1).</td><td>Number</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code>:<code>id</code></td><td>Un identificador único de Oxylabs para el trabajo específico.</td><td>Integer</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code>:<code>create_status_code</code></td><td>Código de estado HTTP devuelto cuando se creó el trabajo, que indica la aceptación inicial de la solicitud del trabajo.</td><td>Integer</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code>:<code>result_status</code></td><td>El estado de ejecución del trabajo (por ejemplo, "done", "failed", "pending").</td><td>String</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code>:<code>created_at</code></td><td>Marca de tiempo cuando se creó el trabajo</td><td>String</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code>:<code>result_created_at</code></td><td>Marca de tiempo cuando el trabajo se completó y produjo un resultado</td><td>String</td></tr></tbody></table>

### Obtener trabajos programados

#### Descripción general

Usa este endpoint para obtener la lista de trabajos de scraping ejecutados como resultado de ejecutar una programación.&#x20;

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/jobs`
* **Método**: `GET`
* **Autenticación**: `Basic`

#### Salida

El payload abajo contiene una respuesta de información de programación de ejemplo.

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

### Obtener información de la programación

#### Descripción general

Usa este endpoint para obtener información sobre una programación específica.&#x20;

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}`
* **Método**: `GET`
* **Autenticación**: `Basic`

#### Salida

El payload abajo contiene una respuesta de información de programación de ejemplo.

<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">Clave</th><th>Descripción</th><th>Tipo</th></tr></thead><tbody><tr><td><code>schedule_id</code></td><td>El ID único de la programación.</td><td>Integer</td></tr><tr><td><code>active</code></td><td>¿La programación está activa ahora?</td><td>Boolean</td></tr><tr><td><code>items_count</code></td><td>El número de elementos (trabajos) en la programación.</td><td>Integer</td></tr><tr><td><code>cron</code></td><td>La expresión cron asociada con la programación.</td><td>String</td></tr><tr><td><code>end_time</code></td><td>La hora en la que la programación dejará de repetirse.</td><td>String</td></tr><tr><td><code>next_run_at</code></td><td>La hora en la que la programación se ejecutará a continuación.</td><td>String</td></tr><tr><td><code>links</code></td><td>Una colección de objetos link que definen los endpoints API disponibles relacionados con un recurso de programación.</td><td>Array</td></tr><tr><td><code>links</code>:<code>rel</code></td><td>El identificador de relación que explica el propósito del enlace en relación con el recurso padre.</td><td>String</td></tr><tr><td><code>links</code>:<code>href</code></td><td>La ruta URL al endpoint de la API. Representa la ubicación del recurso que se puede acceder.</td><td>String</td></tr><tr><td><code>links</code>:<code>método</code></td><td>El método HTTP que se debe usar al acceder a este endpoint.</td><td>String</td></tr><tr><td><code>stats</code></td><td>Contiene estadísticas de creación y finalización de trabajos.</td><td>JSON Object</td></tr><tr><td><code>stats</code>:<code>total_job_count</code></td><td>El número de elementos (trabajos) en la programación.</td><td>Integer</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code></td><td>Contiene estadísticas de creación de trabajos.</td><td>JSON Array</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>status_code</code></td><td>El código de estado recibido en respuesta a un intento de ejecutar la programación (crear un trabajo de scraping/parsing).</td><td>Integer</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>job_count</code></td><td>El número de intentos de creación de trabajos que resultaron en ese código de estado particular.</td><td>Integer</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code>:<code>ratio</code></td><td>La proporción entre el número de intentos de creación de trabajos que resultaron en ese intento particular y el número total de intentos de creación de trabajos.</td><td>Float</td></tr><tr><td><code>job_result_outcomes</code></td><td>Contiene las estadísticas de resultados de los trabajos de scraping/parsing ejecutados como parte de la programación.</td><td>JSON Array</td></tr><tr><td><code>estado</code></td><td>El estado del trabajo. Valores posibles: <code>pending</code> (el trabajo aún se está procesando), <code>done</code> (el trabajo se ha completado con éxito), <code>faulted</code> (el trabajo ha fallado).</td><td>String</td></tr><tr><td><code>job_count</code></td><td>El número de trabajos que resultaron en ese <code>estado</code>.</td><td>Integer</td></tr><tr><td><code>ratio</code></td><td>La proporción entre el número de trabajos con ese estado particular y el número total de trabajos creados.</td><td>Float</td></tr></tbody></table>

### Desactivar o reactivar una programación

#### Descripción general

Usa este endpoint para activar o desactivar una programación en particular.

* **Endpoint**: `https://data.oxylabs.io/v1/schedules/{id}/state`
* **Método**: `PUT`
* **Autenticación**: `Basic`

#### Entrada

Usa este endpoint para detener o reiniciar una programación.&#x20;

Al establecer `active` to `false`, puedes detener la ejecución de una programación en particular.&#x20;

Si estableces `active` to `true`, puedes reactivar una programación previamente detenida.

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

**Salida**

```json
null
```

La respuesta estándar es un cuerpo de respuesta vacío con un `202` código de estado.

## Códigos de respuesta de la API

Para códigos de respuesta de la API, consulta [**API**](https://developers.oxylabs.io/documentation/es/soluciones-de-scraping/response-codes#api) sección.