# Scheduler

[**Scheduler**](https://oxylabs.io/features/scheduler) es un **una función gratuita** de Web Scraper API que te permite automatizar trabajos recurrentes de scraping y análisis creando programaciones. 

Mira el tutorial en video a continuación para saber 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 [**función de carga a almacenamiento en la nube**](/products/es/web-scraper-api/features/result-processing-and-storage/cloud-storage.md) . De esta manera, puedes configurar tu programación y recibir actualizaciones regulares de datos en tu almacenamiento sin intentar obtener resultados de 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 que eso esté establecido, 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 sencillos pasos a continuación.

1. Dinos **con qué frecuencia debemos repetir los trabajos** enviando una expresión cron de programación;
2. Danos **un conjunto de parámetros de trabajo** que debemos ejecutar en los horarios programados;
3. Indícanos **cuándo detenerlo** 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" %}
**NOTA**: 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. ¿Eres nuevo en Postman? Aprende más sobre esta herramienta [**aquí**](broken://spaces/P91ya1mpAK3bvuNKJQ1c/pages/7e1f7b8481bad4953687471a9a04f5dc5ac6b686).
{% 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

#### Resumen

Usa este endpoint para iniciar una nueva programación.

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

**Entrada**

<table><thead><tr><th width="125">Parámetro</th><th width="477.3333333333333">Descripción</th><th>Valor predeterminado</th></tr></thead><tbody><tr><td><mark style="background-color:green;"><strong><code>cron</code></strong></mark></td><td>Expresión cron de programación. Determina con qué frecuencia se ejecutará la programación enviada. Leer 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="background-color:green;"><strong><code>items</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="background-color:green;"><strong><code>end_time</code></strong></mark></td><td>La hora en la que la programación debe dejar de ejecutarse. Nota: la hora de finalización es inclusiva.</td><td>-</td></tr></tbody></table>

&#x20;    \- parámetro obligatorio

{% hint style="info" %}
**NOTA**: Para obtener orientación sobre cómo preparar conjuntos de parámetros de trabajo para la **`items`** parte de tu carga útil de Scheduler, consulta la página de documentación del scraper específico que quieras usar (por ejemplo, [**Google**](/api-targets/es/motores-de-busqueda/google.md), [**Amazon**](/api-targets/es/comercio-electronico/amazon.md), etc.).
{% endhint %}

La carga útil a continuación hará que Scheduler ejecute dos trabajos programados a las 03:00 los lunes hasta `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"
}
```

#### Salida

La respuesta a continuación 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

#### Resumen

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

#### Salida

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

Consulta la respuesta de ejemplo a continuación.

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

### Obtener información de las ejecuciones

#### Resumen

Usa este endpoint para obtener información sobre una lista de todas las ejecuciones de 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**: `Básico`

#### Salida

La carga útil a continuación 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 de ejecución 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>Entero</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code></td><td>Una colección de objetos de trabajo 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 (varía de 0 a 1).</td><td>Número</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>Entero</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 de trabajo.</td><td>Entero</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>Cadena</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code>:<code>created_at</code></td><td>Marca de tiempo en la que se creó el trabajo</td><td>Cadena</td></tr><tr><td><code>ejecuciones</code>:<code>jobs</code>:<code>result_created_at</code></td><td>Marca de tiempo en la que el trabajo se completó y generó un resultado</td><td>Cadena</td></tr></tbody></table>

### Obtener trabajos programados

#### Resumen

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

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

#### Salida

La carga útil a continuación contiene una respuesta de información de programación de ejemplo.

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

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

#### Resumen

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

#### Salida

La carga útil a continuación 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>Entero</td></tr><tr><td><code>active</code></td><td>¿La programación está activa ahora mismo?</td><td>Booleano</td></tr><tr><td><code>items_count</code></td><td>El número de elementos (trabajos) en la programación.</td><td>Entero</td></tr><tr><td><code>cron</code></td><td>La expresión cron asociada con la programación.</td><td>Cadena</td></tr><tr><td><code>end_time</code></td><td>La hora en la que la programación dejará de repetirse.</td><td>Cadena</td></tr><tr><td><code>next_run_at</code></td><td>La hora en la que se ejecutará la programación la próxima vez.</td><td>Cadena</td></tr><tr><td><code>enlaces</code></td><td>Una colección de objetos de enlace que definen los endpoints de API disponibles relacionados con un recurso de programación.</td><td>Array</td></tr><tr><td><code>enlaces</code>:<code>rel</code></td><td>El identificador de relación que explica el propósito del enlace con respecto al recurso padre.</td><td>Cadena</td></tr><tr><td><code>enlaces</code>:<code>href</code></td><td>La ruta URL al endpoint de API. Representa la ubicación del recurso a la que se puede acceder.</td><td>Cadena</td></tr><tr><td><code>enlaces</code>:<code>método</code></td><td>El método HTTP que se usará al acceder a este endpoint.</td><td>Cadena</td></tr><tr><td><code>stats</code></td><td>Contiene estadísticas de creación de trabajos y finalización de trabajos.</td><td>Objeto JSON</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>Entero</td></tr><tr><td><code>stats</code>:<code>job_create_outcomes</code></td><td>Contiene estadísticas de creación de trabajos.</td><td>Array JSON</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/análisis).</td><td>Entero</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>Entero</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/análisis ejecutados como parte de la programación.</td><td>Array JSON</td></tr><tr><td><code>status</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 correctamente), <code>faulted</code> (el trabajo ha fallado).</td><td>Cadena</td></tr><tr><td><code>job_count</code></td><td>El número de trabajos que resultaron en ese estado particular <code>status</code>.</td><td>Entero</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

#### Resumen

Usa este endpoint para activar o desactivar una programación específica.

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

#### Entrada

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

Al establecer `active` a `false`, puedes detener la ejecución de una programación específica.&#x20;

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

```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 los códigos de respuesta de la API, consulta [**API**](/products/es/web-scraper-api/response-codes.md#api) sección.


---

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