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

# Schedules SDK Reference

> Manage agent schedules with the Node.js and Python SDKs: list, create, update, delete, and trigger cron-based runs of your Orq.ai agents.

## Schedules

### List Schedules

Lists all schedules attached to the specified agent, most recent first.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.schedules.list(agent_key="<value>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.schedules.list({
      agentKey: "<value>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "schedules": [{
            "id": str,
            "agent_key": str,
            "agent_tag": Optional[str],
            "created": str,
            "created_by_id": str,
            "display_name": Optional[str],
            "expression": str,
            "generation": int,
            "is_active": bool,
            "last_triggered_at": str,  # optional
            "payload": {
                "input": Optional[Any],
                "memory_entity_id": Optional[str],
                "metadata": Dict[str, str],  # optional
                "variables": Dict[str, Any],  # optional
            },
            "trigger_count": int,
            "type": Literal["cron", "once", "interval"],
            "updated": str,
            "updated_by_id": Optional[str],
        }],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      schedules: {
        id: string;
        agentKey: string;
        agentTag?: string;
        created: Date;
        createdById: string;
        displayName?: string;
        expression: string;
        generation: number;
        isActive: boolean;
        lastTriggeredAt?: Date;
        payload: {
          input?: any;
          memoryEntityId?: string;
          metadata?: Record<string, string>;
          variables?: Record<string, any>;
        };
        triggerCount: number;
        type: "cron" | "once" | "interval";
        updated: Date;
        updatedById?: string;
      }[];
    }
    ```
  </CodeGroup>
</Expandable>

### Create a Schedule

Creates a schedule that runs the agent on a cron cadence. Only `cron` is accepted, as a 6-field expression firing at most once per hour: hourly `0 0 * * * *`, daily `0 0 9 * * *`, or weekly `0 0 9 * * 1`.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.schedules.create(agent_key="<value>", display_name="Daily morning briefing", expression="0 0 9 * * *", payload={
          "input": "Generate the morning briefing for {{region}}",
          "memory_entity_id": "mem_entity_123",
          "metadata": {
              "run_source": "daily-briefing",
          },
          "variables": {
              "region": "EMEA",
          },
      }, type_="cron", agent_tag="v2")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.schedules.create({
      agentKey: "<value>",
      requestBody: {
        agentTag: "v2",
        displayName: "Daily morning briefing",
        expression: "0 0 9 * * *",
        payload: {
          input: "Generate the morning briefing for {{region}}",
          memoryEntityId: "mem_entity_123",
          metadata: {
            "run_source": "daily-briefing",
          },
          variables: {
            "region": "EMEA",
          },
        },
        type: "cron",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "display_name": str,  # required
        "expression": str,  # required
        "payload": {  # required
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, str],  # optional
            "variables": Dict[str, Any],  # optional
        },
        "type": Literal["cron"],  # required
        "agent_tag": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      requestBody: {  // required
        agentTag?: string;
        displayName: string;  // required
        expression: string;  // required
        payload: {  // required
          input?: any;
          memoryEntityId?: string;
          metadata?: Record<string, string>;
          variables?: Record<string, any>;
        };
        type: "cron";  // required
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "agent_key": str,
        "agent_tag": Optional[str],
        "created": str,
        "created_by_id": str,
        "display_name": Optional[str],
        "expression": str,
        "generation": int,
        "is_active": bool,
        "last_triggered_at": str,  # optional
        "payload": {
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, str],  # optional
            "variables": Dict[str, Any],  # optional
        },
        "trigger_count": int,
        "type": Literal["cron", "once", "interval"],
        "updated": str,
        "updated_by_id": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      agentKey: string;
      agentTag?: string;
      created: Date;
      createdById: string;
      displayName?: string;
      expression: string;
      generation: number;
      isActive: boolean;
      lastTriggeredAt?: Date;
      payload: {
        input?: any;
        memoryEntityId?: string;
        metadata?: Record<string, string>;
        variables?: Record<string, any>;
      };
      triggerCount: number;
      type: "cron" | "once" | "interval";
      updated: Date;
      updatedById?: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Delete a Schedule

Permanently removes the schedule. It will not run again.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      orq.schedules.delete(agent_key="<value>", schedule_id="<id>")

      # Use the SDK ...

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    await orq.schedules.delete({
      agentKey: "<value>",
      scheduleId: "<id>",
    });

  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "schedule_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      scheduleId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

### Retrieve a Schedule

Retrieves a single schedule by ID.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.schedules.retrieve(agent_key="<value>", schedule_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.schedules.retrieve({
      agentKey: "<value>",
      scheduleId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "schedule_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      scheduleId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "agent_key": str,
        "agent_tag": Optional[str],
        "created": str,
        "created_by_id": str,
        "display_name": Optional[str],
        "expression": str,
        "generation": int,
        "is_active": bool,
        "last_triggered_at": str,  # optional
        "payload": {
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, str],  # optional
            "variables": Dict[str, Any],  # optional
        },
        "trigger_count": int,
        "type": Literal["cron", "once", "interval"],
        "updated": str,
        "updated_by_id": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      agentKey: string;
      agentTag?: string;
      created: Date;
      createdById: string;
      displayName?: string;
      expression: string;
      generation: number;
      isActive: boolean;
      lastTriggeredAt?: Date;
      payload: {
        input?: any;
        memoryEntityId?: string;
        metadata?: Record<string, string>;
        variables?: Record<string, any>;
      };
      triggerCount: number;
      type: "cron" | "once" | "interval";
      updated: Date;
      updatedById?: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Update a Schedule

Partially updates a schedule. Any omitted field is left unchanged. Changing `expression` or `type` (or reactivating from inactive) reschedules the next run and bumps `generation`; payload-only and `agent_tag`-only changes leave the firing cadence in place.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.schedules.update(agent_key="<value>", schedule_id="<id>", expression="0 0 9 * * *")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.schedules.update({
      agentKey: "<value>",
      scheduleId: "<id>",
      requestBody: {
        expression: "0 0 9 * * *",
      },
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "schedule_id": str,  # required
        "agent_tag": Optional[str],
        "display_name": Optional[str],
        "expression": Optional[str],
        "is_active": Optional[bool],
        "payload": {  # optional
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, str],  # optional
            "variables": Dict[str, Any],  # optional
        },
        "type": Optional[Literal["cron"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      scheduleId: string;  // required
      requestBody: {  // required
        agentTag?: string;
        displayName?: string;
        expression?: string;
        isActive?: boolean;
        payload?: {
          input?: any;
          memoryEntityId?: string;
          metadata?: Record<string, string>;
          variables?: Record<string, any>;
        };
        type?: "cron";
      };
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "id": str,
        "agent_key": str,
        "agent_tag": Optional[str],
        "created": str,
        "created_by_id": str,
        "display_name": Optional[str],
        "expression": str,
        "generation": int,
        "is_active": bool,
        "last_triggered_at": str,  # optional
        "payload": {
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, str],  # optional
            "variables": Dict[str, Any],  # optional
        },
        "trigger_count": int,
        "type": Literal["cron", "once", "interval"],
        "updated": str,
        "updated_by_id": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      id: string;
      agentKey: string;
      agentTag?: string;
      created: Date;
      createdById: string;
      displayName?: string;
      expression: string;
      generation: number;
      isActive: boolean;
      lastTriggeredAt?: Date;
      payload: {
        input?: any;
        memoryEntityId?: string;
        metadata?: Record<string, string>;
        variables?: Record<string, any>;
      };
      triggerCount: number;
      type: "cron" | "once" | "interval";
      updated: Date;
      updatedById?: string;
    }
    ```
  </CodeGroup>
</Expandable>

### Trigger a Schedule

Runs the schedule's payload immediately (approximately 10 seconds after the request). The schedule's regular cadence is unaffected. Inactive schedules return 400.

<CodeGroup>
  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  from orq_ai_sdk import Orq
  import os

  with Orq(
      api_key=os.getenv("ORQ_API_KEY", ""),
  ) as orq:

      res = orq.schedules.trigger(agent_key="<value>", schedule_id="<id>")

      # Handle response
      print(res)

  ```

  ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import { Orq } from "@orq-ai/node";

  const orq = new Orq({
    apiKey: process.env["ORQ_API_KEY"] ?? "",
  });

  async function run() {
    const result = await orq.schedules.trigger({
      agentKey: "<value>",
      scheduleId: "<id>",
    });

    console.log(result);
  }

  run();
  ```
</CodeGroup>

<Expandable title="Parameters">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "agent_key": str,  # required
        "schedule_id": str,  # required
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      scheduleId: string;  // required
    }
    ```
  </CodeGroup>
</Expandable>

<Expandable title="Response">
  <CodeGroup>
    ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
        "schedule_id": str,
        "status": str,
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      scheduleId: string;
      status: string;
    }
    ```
  </CodeGroup>
</Expandable>


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