# Run on a schedule (/docs/schedules)

Every run is one-shot. To repeat one, call `POST /v1/run` from a scheduler you already use.
Each scheduled run is billed like any other run.

## GitHub Actions

The [bowmark-watch](https://github.com/bowmark-ai/bowmark-watch) template runs a script every
day, compares the rows with the last run, and opens an issue when something changed.

    Click **Use this template** on
    [github.com/bowmark-ai/bowmark-watch](https://github.com/bowmark-ai/bowmark-watch).

    In your copy, add a repository secret named `BOWMARK_API_KEY` (**Settings > Secrets and
    variables > Actions**).

    Edit `watch.js` to return the rows you care about, each with a stable `key`.

    Run **Actions > watch > Run workflow** once to record the starting point.

To add it to a workflow you already have, the step is one call:

```yaml
on:
  schedule:
    - cron: "0 14 * * *" # every day at 14:00 UTC
  workflow_dispatch:
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Run a Bowmark script
        env:
          BOWMARK_API_KEY: ${{ secrets.BOWMARK_API_KEY }}
        run: |
          curl -s https://api.bowmark.ai/v1/run \
            -H "authorization: Bearer $BOWMARK_API_KEY" \
            -H "content-type: application/json" \
            -d '{"script":"return await bowmark.read.page(\"https://example.com\")"}' \
            > result.json
```

## Zapier or Make

No code needed. The script is one fixed piece of text you paste in once.

  **Zapier**
    1. **Trigger:** "Schedule by Zapier", set to weekly.
    2. **Call Bowmark:** a "Webhooks by Zapier: POST" step to `https://api.bowmark.ai/v1/run`, with
       header `Authorization: Bearer <your BOWMARK_API_KEY>` and this JSON body:
       ```json
       { "script": "const { flights } = await bowmark.flights.search({ from: 'OSL', to: 'AMS', depart: '2026-12-01' }); return flights;" }
       ```
    3. Zapier parses the reply. `result` is the array this run found.
    4. **Loop over `result`** with "Looping by Zapier". Inside the loop, use Airtable's **"Find
       Record"** (by the row's URL), then **"Create Record"** when nothing was found.

  **Make**
    1. **Trigger:** a "Schedule" module, weekly.
    2. **Call Bowmark:** an "HTTP: Make a request" module, `POST` to
       `https://api.bowmark.ai/v1/run`, header `Authorization: Bearer <your BOWMARK_API_KEY>`, body
       type JSON:
       ```json
       { "script": "const { flights } = await bowmark.flights.search({ from: 'OSL', to: 'AMS', depart: '2026-12-01' }); return flights;" }
       ```
    3. Make parses the response. `result` is the array this run found.
    4. **Iterate `result`** with the Iterator module. Per item, use Airtable's **"Search Records"**
       (by the row's URL), then **"Create a Record"** when the search is empty.

The Find-then-Create pair is what reports only new rows. Swap the one-line script for any
check you need, such as `bowmark.read.page(url)`.

## A button someone else can press

To let someone re-run a check whenever they like, swap the schedule trigger for a manual one.
Everything after the trigger stays the same.

  **Zapier**
    1. **Trigger:** "Webhooks by Zapier: Catch Hook", or a form (Zapier Interfaces, Google Forms)
       wired to the Zap.
    2. Keep the "Call Bowmark", parse and Airtable steps from above.
    3. Share the trigger URL or form link. The person never sees the script or the key.

  **Make**
    1. **Trigger:** a "Webhooks: Custom webhook" module, or the scenario's own **Run once** button.
    2. Keep the other steps from above.
    3. For someone who should not need Make, put the webhook behind a bookmarked link, a Google
       Form, or an Airtable button field.

## Keep results between runs

`bowmark.files` saves files to your account, so the next run can read the last one. No
Airtable needed.

```js
const { flights } = await bowmark.flights.search({ from: "OSL", to: "AMS", depart: "2026-12-01" });

const prev = (await bowmark.files.list()).find((f) => f.name === "check.json"); // newest first
const seen = prev ? JSON.parse((await bowmark.files.get(prev.id, { content: true })).text) : [];
const fresh = flights.filter((f) => !seen.some((s) => s.url === f.url));

await bowmark.files.save({ name: "check.json", text: JSON.stringify(flights), keepFor: "30d" });
return fresh;
```

| Call                                           | Returns                                                                                          |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `bowmark.files.save({ name, text, keepFor? })` | The saved file. `keepFor` takes `"30m"`, `"1h"`, `"7d"`; without it the file stays until deleted |
| `bowmark.files.list()`                         | Every file on your account, newest first: `{ id, name, bytes, contentType, expiresAt, url }`     |
| `bowmark.files.get(id, { content: true })`     | The file's details plus its `text`                                                               |
| `bowmark.files.get(id)`                        | Details only, with a download `url` valid for 1 hour                                             |
| `bowmark.files.url(id)`                        | A fresh download URL                                                                             |

Files belong to your account, not to one run. Each file is capped at 25 MB.

## Sites that need a login

A scheduled script cannot wait for someone to sign in. Store the login once and the script
signs itself in every run. See
[Signed-in sites](/docs/signed-in-sites#sign-in-from-an-unattended-script).
