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

# Scheduling

> Set how often a workflow runs, start a run on demand, and check when a run has finished.

Run a workflow once, on a repeat interval, or on cron expressions. You can also start a run at any time and check its status.

## Before you begin

* A workflow. See [Create workflows](https://docs.kadoa.com/docs/workflows/create/dashboard.md).
* For the SDK and API, a team [API key](https://docs.kadoa.com/docs/api-keys.md) and an installed SDK: `npm install @kadoa/node-sdk` or `uv add kadoa-sdk`.

## Schedule types

| Dashboard mode | API setting | What it does |
| - | - | - |
| **Run once** | `ONLY_ONCE` | Runs the workflow one time, with no schedule. |
| **Every…** | An [interval](#intervals) such as `HOURLY` or `DAILY` | Repeats at an interval, from every 10 minutes to every month. |
| **Every…** with **At a specific time** | `CUSTOM` with one cron expression | Runs at a time of day you pick, on the days of the week or month you pick. Available for every day, week, or month. |
| **Advanced** | `CUSTOM` with cron expressions in `schedules` | Runs on one or more cron expressions. |

* **Weekdays only** skips Saturdays and Sundays. It applies to repeat intervals only. For cron, set the weekdays in the expression, such as `MON-FRI`.
* Cron schedules follow the timezone you pick, including daylight saving time. The default is UTC.
* Real-time workflows have no schedule. They watch the source continuously. To create one, choose **Real-time** in the setup prompt. See [Monitors](https://docs.kadoa.com/docs/monitors.md).
* If the workflow is linked to a [template](https://docs.kadoa.com/docs/templates.md) that sets the frequency, change the frequency in the template.

## Set a schedule

**Dashboard**

1. Open the workflow and select **Frequency** in the side rail.
2. Select **Run once**, **Every…**, or **Advanced**.
3. For **Every…**, pick the interval. To run at a set time, turn on **At a specific time** and pick the days and time.
4. For **Advanced**, enter one cron expression per line, for example `0 9 * * MON-FRI`.
5. Optional: turn on **Weekdays only**, or pick a **Timezone** when the panel shows one.
6. Select **Save**.

![The Frequency panel with Run once, Every…, and Advanced modes, a daily interval, a specific time, and the timezone](https://mintcdn.com/kadoa/uOUjTkH3SuEJThMI/images/workflows/frequency.png?fit=max\&auto=format\&n=uOUjTkH3SuEJThMI\&q=85\&s=b5b7d172fdad37698f90bed4845d5b47)

**SDK & API**

Set the schedule when you create the workflow. This example runs at 9:00 and 18:00 UTC on weekdays:

```typescript Node SDK theme={null}
const workflow = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/ecommerce/pagination"],
    name: "Scheduled Extraction",
    extraction: (builder) =>
      builder
        .entity("Product")
        .field("title", "Product name", "STRING", { example: "Sample" }),
  })
  .setInterval({
    schedules: ["0 9 * * MON-FRI", "0 18 * * MON-FRI"],
  })
  .create();

// Workflow runs automatically on schedule
console.log("Scheduled workflow:", workflow.workflowId);
```

```python Python SDK theme={null}
from kadoa_sdk import ExtractOptions, FieldOptions, KadoaClient, KadoaClientConfig

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

workflow = (
    client.extract(
        ExtractOptions(
            urls=["https://sandbox.kadoa.com/ecommerce/pagination"],
            name="Scheduled Extraction",
            extraction=lambda builder: builder.entity("Product").field(
                "title", "Product name", "STRING", FieldOptions(example="Sample")
            ),
        )
    )
    .set_interval({"schedules": ["0 9 * * MON-FRI", "0 18 * * MON-FRI"]})
    .create()
)

# Workflow runs automatically on schedule
print("Scheduled workflow:", workflow.workflow_id)
```

```bash REST API theme={null}
curl -X POST https://api.kadoa.com/v4/workflows \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://sandbox.kadoa.com/ecommerce/pagination"],
    "name": "Scheduled Extraction",
    "interval": "CUSTOM",
    "schedules": ["0 9 * * MON-FRI", "0 18 * * MON-FRI"],
    "entity": "Product",
    "fields": [{"name": "title", "dataType": "STRING", "description": "Product name"}]
  }'
```

To evaluate cron expressions in another timezone, pass `timezone` with an IANA name such as `America/New_York`. To change the schedule of an existing workflow, see [Update a workflow](https://docs.kadoa.com/docs/workflows/manage.md#update-a-workflow).

**MCP**

Ask your AI tool, for example:

```text theme={null}
> "Create a workflow to extract products from sandbox.kadoa.com/ecommerce/pagination, scheduled at 9am and 6pm on weekdays"
```

Your AI tool calls `create_workflow` with `updateInterval` set to `CUSTOM` and cron expressions in `schedules`. For an existing workflow, it calls `update_workflow`, which also takes `timezone`. Changing only the timezone keeps the existing cron expressions.

## Run a workflow now

**Dashboard**

1. Open the workflow.
2. Select **Run now** in the header.

**SDK & API**

```typescript Node SDK theme={null}
const workflow = await client.workflow.get(workflowId);
console.log(`Current workflow state: ${workflow.displayState}`);

const result = await client.workflow.runWorkflow(workflowId, {
  limit: 10,
});
console.log(`Workflow scheduled with runId: ${result.jobId}`);
```

```python Python SDK theme={null}
from kadoa_sdk import KadoaClient, KadoaClientConfig, RunWorkflowOptions

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))
workflow_id = "YOUR_WORKFLOW_ID"

workflow = client.workflow.get(workflow_id)
print(f"Current workflow state: {workflow.display_state}")

result = client.workflow.run_workflow(
    workflow_id,
    input=RunWorkflowOptions(limit=10),
)
print(f"Workflow scheduled with runId: {result.job_id}")
```

```bash REST API theme={null}
curl -X PUT https://api.kadoa.com/v4/workflows/YOUR_WORKFLOW_ID/run \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json"
```

```json Response theme={null}
{
  "success": true,
  "jobId": "job_abc123"
}
```

**MCP**

Ask your AI tool, for example:

```text theme={null}
> "Run my 'Scheduled Extraction' workflow with a limit of 10 records"
```

Your AI tool calls `run_workflow`.

## Check run status

Poll the workflow status to know when the extraction is complete.

**Dashboard**

1. Open the workflow. The badge next to its name shows the current state, such as **Running**, **Scheduled**, or **Complete**.
2. To see earlier runs, select **History** in the side rail, then select **Runs**.

See [Lifecycle](https://docs.kadoa.com/docs/workflows/lifecycle.md) for every badge.

**SDK & API**

```typescript Node SDK theme={null}
const extraction = await client
  .extract({
    urls: ["https://sandbox.kadoa.com/ecommerce/pagination"],
    name: "Paginated Extraction",
    userPrompt: "Extract all products, paginating through all pages",
    extraction: (builder) =>
      builder
        .entity("Product")
        .field("title", "Product name", "STRING", {
          example: "Sennheiser HD 6XX",
        })
        .field("price", "Product price", "MONEY"),
  })
  .create();

const result = await extraction.run({ limit: 10 });

// Fetch a single page with pagination info
const page = await result.fetchData({ page: 1, limit: 5 });
console.log("Page data:", page.data);
console.log("Pagination:", page.pagination);

// Or get all data at once
const allData = await result.fetchAllData({});
console.log("All data:", allData);
```

```python Python SDK theme={null}
from kadoa_sdk import (
    ExtractOptions,
    FieldOptions,
    KadoaClient,
    KadoaClientConfig,
    RunWorkflowOptions,
)

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

extraction = (
    client.extract(
        ExtractOptions(
            urls=["https://sandbox.kadoa.com/ecommerce/pagination"],
            name="Paginated Extraction",
            user_prompt="Extract all products, paginating through all pages",
            extraction=lambda builder: builder.entity("Product")
            .field(
                "title",
                "Product name",
                "STRING",
                FieldOptions(example="Sennheiser HD 6XX"),
            )
            .field("price", "Product price", "MONEY"),
        )
    )
    .create()
)

result = extraction.run(RunWorkflowOptions(limit=10))

# Fetch a single page with pagination info
page = result.fetch_data({"page": 1, "limit": 5})
print("Page data:", page.data)
print("Pagination:", page.pagination)

# Or get all data at once
all_data = result.fetch_all_data({})
print("All data:", all_data)
```

```bash REST API theme={null}
# 1. Run workflow
curl -X PUT https://api.kadoa.com/v4/workflows/YOUR_WORKFLOW_ID/run \
  -H "x-api-key: YOUR_API_KEY"

# 2. Poll status until complete
curl -X GET https://api.kadoa.com/v4/workflows/YOUR_WORKFLOW_ID \
  -H "x-api-key: YOUR_API_KEY"

# 3. Once runState is "FINISHED", fetch data
curl -X GET https://api.kadoa.com/v4/workflows/YOUR_WORKFLOW_ID/data \
  -H "x-api-key: YOUR_API_KEY"
```

```json Response (Status) theme={null}
{
  "id": "507f1f77bcf86cd799439011",
  "name": "My Workflow",
  "state": "ACTIVE",
  "displayState": "RUNNING",
  "runState": "RUNNING",
  "jobId": "job_abc123"
}
```

`runState` holds the state of the latest run:

* `RUNNING`: the extraction is running.
* `FINISHED`: the data is ready to retrieve.
* `FAILED`: the extraction failed. Check the `errors` field.
* `STOPPED`: the run was stopped.

**MCP**

Ask your AI tool, for example:

```text theme={null}
> "Has my 'Paginated Extraction' workflow finished?"
```

Your AI tool calls `get_workflow` for the current status, or `list_workflow_runs` for the run history.

## Get notified about changes

A scheduled workflow compares each run with the previous one. To hear about changes in the dashboard, open the workflow and select **Notifications** in the side rail. Subscribe to the **Data changes** event. You can limit alerts to certain fields, change types, or conditions. See [Notifications](https://docs.kadoa.com/docs/notifications.md) and [Change detection](https://docs.kadoa.com/docs/change-detection.md).

To start another workflow when data changes, see [Triggers](https://docs.kadoa.com/docs/ui/workflows/triggers.md).

## Intervals

A workflow's interval is one of these values:

| Interval | Description |
| - | - |
| `ONLY_ONCE` | Run once |
| `EVERY_10_MINUTES` | Every 10 minutes |
| `EVERY_20_MINUTES` | Every 20 minutes |
| `HALF_HOURLY` | Every 30 minutes |
| `HOURLY` | Every hour |
| `TWO_HOURLY` | Every 2 hours |
| `THREE_HOURLY` | Every 3 hours |
| `FOUR_HOURLY` | Every 4 hours |
| `SIX_HOURLY` | Every 6 hours |
| `TWELVE_HOURLY` | Every 12 hours |
| `EIGHTEEN_HOURLY` | Every 18 hours |
| `DAILY` | Once per day |
| `TWO_DAY` | Every 2 days |
| `THREE_DAY` | Every 3 days |
| `WEEKLY` | Once per week |
| `BIWEEKLY` | Every 2 weeks |
| `TRIWEEKLY` | Every 3 weeks |
| `FOUR_WEEKS` | Every 4 weeks |
| `MONTHLY` | Once per month |
| `REAL_TIME` | [Real-time monitoring](https://docs.kadoa.com/docs/workflows/agent.md) |
| `CUSTOM` | Use cron expressions |

## Related

* [Create workflows](https://docs.kadoa.com/docs/workflows/create/dashboard.md)
* [Prompts](https://docs.kadoa.com/docs/workflows/prompts.md)
* [Notifications](https://docs.kadoa.com/docs/notifications.md)
* [Schedule a workflow API reference](https://docs.kadoa.com/api-reference/workflows/schedule-a-workflow.md)


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