> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peel.sh/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Peel builds APIs from a URL and a task. Use only the REST routes under https://api.peel.sh and the hosted MCP server at https://api.peel.sh/mcp. Authenticate with the X-API-Key header, or send the same key as Authorization: Bearer. Errors carry code, message, retryable, retry, docs_url and details; branch on code. The peel CLI and the open-source SDK are not published; do not run npm install peel, which is an unrelated package. The keyless routes need no key and no session: the GET /public/marketplace routes, POST /v1/marketplace/{marketplace_id}/endpoints/{endpoint_name}:call and https://api.peel.sh/mcp/keyless. Account routes take a key or a signed-in session and answer 401 without one. These take only a session from peel.sh and refuse a key: GET /v1/accounts, POST /v1/accounts/join, POST /v1/accounts/{account_id}/leave, POST /v1/team/invites, GET /v1/connected-apps, DELETE /v1/connected-apps/{client_id}, PUT /v1/logins, DELETE /v1/logins, GET /v1/logins/code and the /account/billing routes. Every route with its schemas is in https://docs.peel.sh/openapi.json. Use the exact route, field and error-code names shown in these pages, and read the API Reference tab for request and response schemas.

# Schedules

> Run a read endpoint every hour, day or week and get a webhook when its answer changes.

A schedule runs one data endpoint with fixed input, every 60 to 10080 minutes, and compares each answer with the one before. When the answer differs, Peel sends the `schedule.changed` webhook with the new data. Use it to watch a price, a listing, a release page or a search.

## Create a schedule

```bash theme={null}
curl -X POST https://api.peel.sh/v1/schedules \
  -H "X-API-Key: $PEEL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "api_id": "'"$API_ID"'",
    "endpoint_name": "search_packages",
    "params": { "q": "http router" },
    "every_minutes": 60
  }'
```

The first run starts within a minute and records the answer later runs compare against (`last_outcome: "first"`). Each run after that is `unchanged`, `changed` or `failed`.

| Field | Meaning |
| - | - |
| `api_id`, `endpoint_name` | The endpoint to run. It must be a data endpoint that needs no sign-in. |
| `params` | The endpoint's input, as you would send it to `:call`. |
| `shape` | Optional. A [shape](https://docs.peel.sh/features/shapes.md) applied to each answer before it is compared and sent. |
| `every_minutes` | 60 to 10080: hourly to weekly. |

`GET /v1/schedules` lists your schedules with `next_run_at`, `last_run_at`, `last_outcome` and `last_error`. When Peel stops reading a site at its owner's request, the site's schedules pause: `next_run_at` is `null` and `last_error` is `site_owner_blocked`. Schedules made later start paused. `DELETE /v1/schedules/{id}` stops one. An account can have 20. Over MCP, use `create_schedule`, `list_schedules` and `delete_schedule`.

## Hear about changes

Subscribe a [webhook](https://docs.peel.sh/features/webhooks.md) to `schedule.changed` and `schedule.failed`.

| Event | `data` |
| - | - |
| `schedule.changed` | `schedule_id`, `api_id`, `endpoint_name`, and `data`, the new answer. Above 64 KB, `data_omitted: true` instead; call the endpoint to read it. |
| `schedule.failed` | `schedule_id`, `api_id`, `endpoint_name` and `error`, the error code of the run. |

Peel compares the whole answer, so a field that changes on every request, such as a timestamp the site prints, makes every run count as changed. Give the schedule a `shape` that picks only the fields you watch.

## What it costs

Each run is a call to the endpoint and counts against your runs like any other call; it shows in [Runs](https://docs.peel.sh/features/runs.md). A run that the quota refuses fails with `quota_exceeded` and sends `schedule.failed`. An hourly schedule runs 720 times a month; a daily one, 30 times.

| Code | HTTP | Meaning |
| - | - | - |
| `schedule_unsupported` | 400 | The endpoint is not a data endpoint, or it needs a sign-in. |
| `api_not_found`, `endpoint_not_found` | 404 | No such API or endpoint on your account. |
| `schedule_limit` | 409 | The account already has 20 schedules. |
| `schedule_not_found` | 404 | No such schedule to delete. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.