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

> SDK reference for the Schedules API, available in Node.js and Python.

## 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": date,
            "created_by_id": str,
            "expression": str,
            "generation": int,
            "is_active": bool,
            "last_triggered_at": date,
            "payload": {
                "input": Optional[Any],
                "memory_entity_id": Optional[str],
                "metadata": Dict[str, Any],
                "variables": Dict[str, Any],
            },
            "trigger_count": int,
            "type": Literal["cron", "once", "interval"],
            "updated": date,
        },
    }
    ```

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

### Create a Schedule

Creates a schedule that runs the agent on a recurring or one-off cadence. The minimum firing interval is 1 hour for `cron` and `interval`; `once` schedules are exempt.

<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>", expression="0 0 9 * * mon-fri", 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",
        expression: "0 0 9 * * mon-fri",
        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
        "expression": str,  # required
        "payload": {  # required
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, Any],
            "variables": Dict[str, Any],
        },
        "type": Literal["cron", "once", "interval"],  # required
        "agent_tag": Optional[str],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      requestBody: {  // required
        agentTag?: string;
        expression: string;  // required
        payload: {  // required
          input?: any;
          memoryEntityId?: string;
          metadata?: Record<string, any>;
          variables?: Record<string, any>;
        };
        type: 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": date,
        "created_by_id": str,
        "expression": str,
        "generation": int,
        "is_active": bool,
        "last_triggered_at": date,
        "payload": {
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, Any],
            "variables": Dict[str, Any],
        },
        "trigger_count": int,
        "type": Literal["cron", "once", "interval"],
        "updated": date,
    }
    ```

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

### Delete a Schedule

Permanently removes a schedule from NATS, Mongo, and the Redis cache.

<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": date,
        "created_by_id": str,
        "expression": str,
        "generation": int,
        "is_active": bool,
        "last_triggered_at": date,
        "payload": {
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, Any],
            "variables": Dict[str, Any],
        },
        "trigger_count": int,
        "type": Literal["cron", "once", "interval"],
        "updated": date,
    }
    ```

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

### Update a Schedule

Partially updates a schedule. Any omitted field is left unchanged. Changing `expression` or `type` (or reactivating from inactive) re-publishes the NATS schedule 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="@every 6h")

      # 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: "@every 6h",
      },
    });

    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],
        "expression": Optional[str],
        "is_active": Optional[bool],
        "payload": {  # optional
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, Any],
            "variables": Dict[str, Any],
        },
        "type": Optional[Literal["cron", "once", "interval"]],
    }
    ```

    ```typescript Node.js theme={"theme":{"light":"github-light","dark":"github-dark"}}
    {
      agentKey: string;  // required
      scheduleId: string;  // required
      requestBody: {  // required
        agentTag?: string;
        expression?: string;
        isActive?: boolean;
        payload?: {
          input?: any;
          memoryEntityId?: string;
          metadata?: Record<string, any>;
          variables?: Record<string, any>;
        };
        type?: string;
      };
    }
    ```
  </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": date,
        "created_by_id": str,
        "expression": str,
        "generation": int,
        "is_active": bool,
        "last_triggered_at": date,
        "payload": {
            "input": Optional[Any],
            "memory_entity_id": Optional[str],
            "metadata": Dict[str, Any],
            "variables": Dict[str, Any],
        },
        "trigger_count": int,
        "type": Literal["cron", "once", "interval"],
        "updated": date,
    }
    ```

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

### Trigger a Schedule

Runs the schedule's payload immediately (≈10 seconds after the request, to stay above the NATS scheduler's minimum deliver-at margin). 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>