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

# Schedule & Run Workflows

> Configure scheduling, run workflows manually, and check execution status

## Prerequisites

* A Kadoa account with API key
* SDK installed: `npm install @kadoa/node-sdk` or `uv add kadoa-sdk`
* An existing workflow ([create one first](/docs/sdk/workflows/create))

## Scheduling Options

Configure when your workflow runs:

<CodeGroup>
  ```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}
  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"}]
    }'
  ```

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

## Available Intervals

| Interval           | Description           |
| ------------------ | --------------------- |
| `ONLY_ONCE`        | Run once              |
| `EVERY_10_MINUTES` | Every 10 minutes      |
| `HALF_HOURLY`      | Every 30 minutes      |
| `HOURLY`           | Every hour            |
| `THREE_HOURLY`     | Every 3 hours         |
| `SIX_HOURLY`       | Every 6 hours         |
| `TWELVE_HOURLY`    | Every 12 hours        |
| `DAILY`            | Once per day          |
| `WEEKLY`           | Once per week         |
| `MONTHLY`          | Once per month        |
| `REAL_TIME`        | Continuous monitoring |
| `CUSTOM`           | Use cron expressions  |

## Manual Execution

Run workflows on demand:

<CodeGroup>
  ```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}
  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 POST https://api.kadoa.com/v4/workflows/YOUR_WORKFLOW_ID/run \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json"
  ```

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

  ```json Response theme={null}
  {
    "success": true,
    "jobId": "job_abc123"
  }
  ```
</CodeGroup>

## Checking Workflow Status

Poll the workflow status to know when extraction is complete:

<CodeGroup>
  ```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}
  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 POST 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 state is "COMPLETED", 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",
    "lastRun": {
      "id": "run-123",
      "state": "IN_PROGRESS",
      "startedAt": "2024-01-15T10:00:00Z",
      "completedAt": null
    }
  }
  ```
</CodeGroup>

**Workflow States:**

* `IN_PROGRESS` - Extraction is running
* `COMPLETED` - Data is ready to retrieve
* `FAILED` - Extraction failed (check errors field)

## Proxy Locations

Specify geographic location for extraction:

<CodeGroup>
  ```typescript Node SDK theme={null}
  const workflow = await client
    .extract({
      urls: ["https://sandbox.kadoa.com/magic"],
      name: "Geo-located Extraction",
      extraction: (builder) =>
        builder
          .entity("Product")
          .field("title", "Title", "STRING", { example: "example" }),
    })
    .setLocation({
      type: "manual",
      isoCode: "US",
    })
    .create();
  ```

  ```python Python SDK theme={null}
  workflow = (
      client.extract(
          ExtractOptions(
              urls=["https://sandbox.kadoa.com/magic"],
              name="Geo-located Extraction",
              extraction=lambda builder: builder.entity("Product").field(
                  "title", "Title", "STRING", FieldOptions(example="example")
              ),
          )
      )
      .set_location({"type": "manual", "isoCode": "US"})
      .create()
  )
  ```

  ```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/magic"],
      "location": {
        "type": "manual",
        "isoCode": "US"
      }
    }'
  ```
</CodeGroup>

**Available locations:**

* `US` - United States
* `GB` - United Kingdom
* `DE` - Germany
* `NL` - Netherlands
* `CA` - Canada
* `auto` - Automatic selection

## Bypass Preview Mode

Skip manual review and activate workflows immediately:

<CodeGroup>
  ```typescript Node SDK theme={null}
  const workflow = await client
    .extract({
      urls: ["https://sandbox.kadoa.com/magic"],
      name: "Direct Activation",
      extraction: (builder) =>
        builder
          .entity("Product")
          .field("title", "Title", "STRING", { example: "example" }),
    })
    .bypassPreview() // Skip review step
    .create();

  // Workflow is immediately active
  ```

  ```python Python SDK theme={null}
  workflow = (
      client.extract(
          ExtractOptions(
              urls=["https://sandbox.kadoa.com/magic"],
              name="Direct Activation",
              extraction=lambda builder: builder.entity("Product").field(
                  "title", "Title", "STRING", FieldOptions(example="example")
              ),
          )
      )
      .bypass_preview()  # Skip review step
      .create()
  )

  # Workflow is immediately active
  ```

  ```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 '{
      "bypassPreview": true,
      "urls": ["https://sandbox.kadoa.com/magic"],
      "entity": "Product",
      "fields": [{"name": "title", "dataType": "STRING", "description": "Title"}]
    }'
  ```
</CodeGroup>

## Next Steps

* [Create Workflows →](/docs/sdk/workflows/create)
* [Writing Prompts →](/docs/workflows/prompts)
* [Configure Notifications →](/docs/sdk/notifications/overview)
* [API Reference →](/api-reference/workflows/schedule-a-workflow)