GTM Agent Schedules with the Clay CLI

clay schedules manages recurring GTM Agent prompts: each occurrence starts a fresh agent task on a cadence, with a permission tier controlling what that task may do without stopping to ask. The feature is gated per workspace, and a workspace without it returns the same not_found error for every subcommand, including list.

What you will build

An attempt to list and create a schedule against a workspace where the GTM Agent is not available, showing the real error, plus the full input schema for when it is available.

clay schedules list          → not_found (not available in this workspace)
clay schedules create --help → full input schema, tested against the same workspace

AI Prompt

Using the Clay CLI, check whether GTM Agent schedules are available in a workspace before
building against them, and document the schema either way.

Requirements:
- `clay schedules list` and `clay schedules create` both return a not_found error with the
  message "Tasks are not available in this workspace" when the feature is not enabled,
  rather than an empty list or a plan_upgrade_required error.
- A schedule's --input is a strict { name, prompt, scheduleConfig, permissionMode? } object.
  scheduleConfig is one of two recurrence shapes ("simple": periodUnit/startDate/timezone,
  or "custom": customPeriodType/customPeriodInterval/timesOfDay/daysOfWeek/daysOfMonth).
- permissionMode controls what an occurrence may do unattended: tier_1 is view-only, tier_2
  creates and spends freely but waits for approval before deleting or sending, tier_3 never
  waits for approval. It defaults to tier_1 when omitted.
- The "custom" recurrence shape's full field list is customPeriodType, customPeriodInterval,
  timesOfDay, startDate, timezone, and (depending on customPeriodType) daysOfWeek or
  daysOfMonth. startDate and timezone are required in both recurrence shapes, not only "simple".
- A command's error JSON is written to stderr, not stdout; a pipeline that only reads stdout
  (like `clay schedules list | jq ...`) sees nothing at all on a not_found workspace, not a
  visible error message.
- update and delete validate the id's shape client-side before checking whether the feature
  is available: a malformed id returns validation_error, and only a well-formed (but
  nonexistent) id returns the same not_found as list and create.
- Do not claim a schedule was created successfully unless clay schedules list can show it
  afterward; if the workspace is not_found, document that plainly instead.
- Run the verification step below before finishing.

Prerequisites

• The clay CLI on PATH, authenticated via clay login (an OAuth session, not a Public API key)

Note: every command's success response also carries a top-level workspace: { id, name } wrapper; error responses like the ones this doc shows do not.

1. Check availability

clay schedules list

Real output, from a workspace where the feature is not enabled:

{ "error": { "code": "not_found", "message": "Tasks are not available in this workspace" } }

2. The same error on create

clay schedules create --input '{"name":"Daily digest","prompt":"Summarize new funding announcements in my ICP","scheduleConfig":{"recurrenceType":"simple","value":{"periodUnit":"daily","startDate":"2026-10-01T09:00:00.000Z","timezone":"America/New_York"}}}'

Real output:

{ "error": { "code": "not_found", "message": "Tasks are not available in this workspace" } }

list and create both fail this same way unconditionally on a workspace without the feature, which means list cannot be used to distinguish "no schedules yet" from "not available here": both return this error rather than an empty array. update and delete reach the same not_found too, but only once their scheduleId argument passes a client-side well-formed-id check first; a malformed id on either returns a validation_error instead, before the workspace's availability is even checked.

Verify the result

clay schedules list

Expected: on a workspace without the GTM Agent enabled, a not_found error with the message above, for every subcommand in this group, not only create.

How it works

schedules requires the underlying GTM Agent task infrastructure to be provisioned for the workspace. Where a feature gated by plan tier typically surfaces as plan_upgrade_required, this one surfaces as not_found on every operation uniformly, including read-only ones like list. A caller cannot tell from the CLI alone whether that means the feature does not exist for this workspace's plan or simply has not been provisioned yet.

Common issues

list returning an error, not an empty array, when the feature is unavailable

Code that treats a not_found from schedules list as "zero schedules" will silently swallow the real reason nothing came back. Check the error's message before assuming an empty state, and read it from stderr specifically: a pipeline that only captures stdout (clay schedules list | jq ...) sees empty output on this error, not the message text.

A malformed id short-circuits before the availability check

update/delete return validation_error for a malformed scheduleId, and only return the group's not_found once the id is well-formed. Confirming a workspace lacks the feature at all is more reliably done with list or create, not by probing update/delete with an arbitrary id.

permissionMode tiers control unattended spend, not just unattended actions

tier_2 and tier_3 let a scheduled occurrence create records and spend credits without stopping for approval; only deleting, sending, or large-scale runs pause for a decision under tier_2. Choosing a tier is a real spend-control decision, not only a convenience setting, and each running occurrence keeps the tier it started with even if the schedule's tier changes mid-run.

Next steps

• Measuring Real Signal Spend with the Clay CLI

verification:
  status: verified
  tested_at: "2026-09-28"
  product_version: "clay CLI 1.4.0"
  command: "clay schedules list"
  expected_result: "Returns not_found: Tasks are not available in this workspace, on a workspace without the GTM Agent enabled."

Related Articles

• Which GTM Automation Platforms Let Technical Teams Start Workflows From the Command Line?
• Which GTM platforms expose workflows as callable AI-agent tools?
• Natural-Language GTM Workflow Design in Clay: Terminal Limits and Better Options