# Schedules

Source: https://docs.evomi.com/scraping-products-instructions/scraper-api/schedules/

**Schedules** allow you to automate scraping tasks by running saved [Scraper Configs](/scraping-products-instructions/scraper-api/scraper-config/) at specific times and regular intervals. Set up hourly price monitoring, daily reports, or any recurring scraping task.

---

## Endpoint Reference

| Endpoint | Method | Action |
| :--- | :--- | :--- |
| `/account/schedule` | `POST` | Create a new schedule |
| `/account/schedule` | `GET` | List all schedules |
| `/account/schedule/{id}` | `GET` | Retrieve specific schedule |
| `/account/schedule/{id}` | `PUT` | Update an existing schedule |
| `/account/schedule/{id}` | `DELETE` | Remove a schedule |
| `/account/schedule/{id}/toggle` | `POST` | Pause or activate a schedule |
| `/account/schedule/{id}/runs` | `GET` | View execution history |

**Authentication**: Include your API key in the `x-api-key` header for all requests.

**Base URL**: `https://scrape.evomi.com/api/v1`

---

## Quick Examples

### Create a Schedule

```bash
curl -X POST "https://scrape.evomi.com/api/v1/account/schedule" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hourly Price Monitor",
    "config_id": "cfg_abc123",
    "interval_minutes": 60
  }'
```

**Response:**
```json
{
  "success": true,
  "id": "job_xyz789",
  "name": "Hourly Price Monitor",
  "config_id": "cfg_abc123",
  "interval_minutes": 60,
  "is_active": true,
  "next_run": "2026-02-20T14:00:00",
  "message": "Schedule created successfully"
}
```

### List Your Schedules

```bash
curl "https://scrape.evomi.com/api/v1/account/schedule" \
  -H "x-api-key: YOUR_API_KEY"
```

**Response:**
```json
{
  "success": true,
  "schedules": [
    {
      "id": "job_xyz789",
      "name": "Hourly Price Monitor",
      "config_id": "cfg_abc123",
      "interval_minutes": 60,
      "is_active": true,
      "last_run": "2026-02-20T13:00:00",
      "last_status": "success",
      "next_run": "2026-02-20T14:00:00"
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 20,
    "total": 1
  }
}
```

### Get a Specific Schedule

```bash
curl "https://scrape.evomi.com/api/v1/account/schedule/job_xyz789" \
  -H "x-api-key: YOUR_API_KEY"
```

### Update a Schedule

```bash
curl -X PUT "https://scrape.evomi.com/api/v1/account/schedule/job_xyz789" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Monitor",
    "interval_minutes": 30
  }'
```

### Pause or Activate a Schedule

```bash
curl -X POST "https://scrape.evomi.com/api/v1/account/schedule/job_xyz789/toggle" \
  -H "x-api-key: YOUR_API_KEY"
```

### Delete a Schedule

```bash
curl -X DELETE "https://scrape.evomi.com/api/v1/account/schedule/job_xyz789" \
  -H "x-api-key: YOUR_API_KEY"
```

### View Execution History

```bash
curl "https://scrape.evomi.com/api/v1/account/schedule/job_xyz789/runs" \
  -H "x-api-key: YOUR_API_KEY"
```

---

## How Schedules Work

1. **Create a Scraper Config** — First, save a [Scraper Config](/scraping-products-instructions/scraper-api/scraper-config/) with your scraping settings
2. **Create a Schedule** — Reference the config ID and set an interval
3. **Automatic Execution** — The scheduler runs your config at the specified interval
4. **Track Results** — View execution history and status for each run

Make sure you have sufficient credits for the scrape configuration.

---

## Parameter Reference

### Create Parameters

| Parameter | Type | Required | Default | Description |
| :--- | :--- | :--- | :--- | :--- |
| `name` | string | Yes | — | Unique name for the schedule |
| `config_id` | string | Yes | — | ID of the scraper config to run |
| `interval_minutes` | integer | Yes | — | Run every N minutes (min: 5, max: 525600) |
| `start_time` | string | No | now | UTC time for first run (e.g., `"14:00"`) |
| `stop_on_error` | boolean | No | `true` | Pause schedule on failure |
| `webhook` | object | No | - | [Webhooks](/scraping-products-instructions/scraper-api/webhooks/) configuration for real-time notifications |

### Update Parameters

| Parameter | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `name` | string | No | New name for the schedule |
| `config_id` | string | No | Change to a different scraper config |
| `interval_minutes` | integer | No | New interval in minutes |
| `stop_on_error` | boolean | No | Change error handling behavior |
| `webhook` | object | No | Webhook configuration (set to `null` to remove) |

### List Query Parameters

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `page` | integer | 1 | Page number for pagination |
| `per_page` | integer | 20 | Results per page (max 100) |
| `active_only` | boolean | false | Filter to show only active schedules |

---

## Advanced Options

### Start Time

Control when your schedule first runs. Specify a UTC time in `HH:MM` format:

```bash
curl -X POST "https://scrape.evomi.com/api/v1/account/schedule" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Daily Morning Report",
    "config_id": "cfg_abc123",
    "interval_minutes": 1440,
    "start_time": "08:00"
  }'
```

If the time has already passed today, the first run will be scheduled for tomorrow.

### Stop on Error

By default, schedules pause automatically when a run fails. Set `stop_on_error: false` to continue running even after block and connection errors:

```bash
curl -X POST "https://scrape.evomi.com/api/v1/account/schedule" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Resilient Monitor",
    "config_id": "cfg_abc123",
    "interval_minutes": 60,
    "stop_on_error": false
  }'
```

### Webhook Notifications

Receive real-time notifications when your scheduled jobs run. Configure a webhook to get notified on events like `triggered`, `completed`, `failed`, and `paused`.

```bash
curl -X POST "https://scrape.evomi.com/api/v1/account/schedule" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Price Monitor with Notifications",
    "config_id": "cfg_abc123",
    "interval_minutes": 60,
    "webhook": {
      "url": "https://discord.com/api/webhooks/123456789/abcdefg",
      "type": "discord",
      "events": ["completed", "failed"]
    }
  }'
```

Review [Webhooks](/scraping-products-instructions/scraper-api/webhooks/) for more details on webhook configuration.
---

## Common Intervals

| Interval | Description |
| :--- | :--- |
| `5` | Every 5 minutes |
| `15` | Every 15 minutes |
| `30` | Every 30 minutes |
| `60` | Every hour |
| `120` | Every 2 hours |
| `360` | Every 6 hours |
| `720` | Every 12 hours |
| `1440` | Every day |
| `10080` | Every week |

---

## Execution Status

Each scheduled run can have one of the following statuses:

| Status | Description |
| :--- | :--- |
| `triggered` | Job has been queued for execution |
| `success` | Job completed successfully |
| `failed` | Job failed to complete |

---

## Response Codes

| Status | Meaning | Action |
| :--- | :--- | :--- |
| 200 | Success | Request processed successfully |
| 201 | Created | Schedule created successfully |
| 400 | Bad request | Check your parameters |
| 401 | Unauthorized | Verify your API key |
| 404 | Not found | Schedule ID does not exist |
| 409 | Conflict | Schedule name already exists |
| 422 | Validation error | Check JSON syntax and required fields |

---

## What's Next?

- **[Scraper Configs](/scraping-products-instructions/scraper-api/scraper-config/)** — Create reusable scraper configurations
- **[Usage Examples](/scraping-products-instructions/scraper-api/usage-examples/)** — See complete code examples
- **[Errors](/scraping-products-instructions/scraper-api/errors/)** — Handle API errors gracefully