Widening or Narrowing a Signal's Schedule with the Clay CLI

Change how often a signal checks its records without touching its targeting or filter, using Clay's real signals update --schedule, and understand why activating a signal can populate lastRunAt well before its schedule would naturally fire again.

What you will build

A schedule change on a live signal, confirmed by reading schedule.periodUnit back, plus the real timing behavior around resume.

clay signals update <id> --schedule weekly
    ↓
{ schedule: { periodUnit: "weekly" } }   (targeting and filter untouched)

AI Prompt

Using the Clay CLI, change how often a signal runs.

Requirements:
- `clay signals update <triggerDefinitionId> --schedule <cadence>`.
  Cadence values: daily, weekly, biweekly, monthly, quarterly, but which
  values a given type accepts depends on what it was created as: topic-
  intent types reject daily; most others accept the full list.
- --schedule is independent of --filter/--input. Changing one never
  touches the others; only what you pass changes.
- Resuming a Paused signal can populate `schedule.lastRunAt` within seconds, not only
  on the next scheduled interval as the resume command's own help text
  states. A schedule change does not eliminate this. Treat any resume as
  a potential near-immediate check regardless of the configured cadence.
- 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)
• An existing signal

Note: JSON samples below are trimmed to the fields relevant to each step. Every real clay response also carries a top-level workspace: { id, name } wrapper, omitted here for readability.

1. Read the current schedule

clay signals get td_0tlqav4Ecpo5M6tsbV9 | jq '.schedule'

2. Widen it from monthly to weekly

clay signals update td_0tlqav4Ecpo5M6tsbV9 --schedule weekly | jq '.schedule'

Real output, only periodUnit changed:

{"id": "01a0c565-c4d5-7a1d-9f54-fb435d44bd49", "periodAmount": 1, "periodUnit": "weekly", "lastRunAt": null}

3. Confirm the filter and targeting are untouched

clay signals get td_0tlqav4Ecpo5M6tsbV9 | jq '{filter, segmentIds: .input.audiences.segmentIds}'

The confidence filter and audience scope remain exactly as they were before the schedule change.

Verify the result

Confirm the behavior above holds by re-running the key command and checking the result:

clay signals update td_0tlqav4Ecpo5M6tsbV9 --schedule weekly

Expected: schedule.periodUnit reflects the new cadence in the response; every other field (filter, input, signal.inputs) is byte-for-byte unchanged from before the update.

How it works

Schedule, filter, and targeting are three independent settings on the same signal record. Tuning one (say, checking weekly instead of monthly because a JobPost signal isn't catching enough postings) does not alter another (the seniority/keyword filter that determines which postings count in the first place). This is the same "only what you pass changes" contract every signals update call follows.

Common issues

Assuming a schedule change resets lastRunAt or run history

Reconfiguring how often something runs can feel like it should restart its run clock. lastRunAt reflects real run history independent of the configured cadence going forward; changing --schedule doesn't clear or reset it.

Assuming a slower schedule delays the very next check

"Runs weekly now" can read as "won't check again for a week." As described in the companion signal-lifecycle example, resuming or reconfiguring a signal can trigger a near-immediate check regardless of the newly configured interval. The schedule governs the steady-state cadence, not necessarily the very next action.

Next steps

• Combine with --clear-filter/--filter to retune both cost levers (frequency and selectivity) together when a signal is producing too much or too little.
• Check clay signals list | jq '.data[] | {id, schedule}'-style reads (via signals get per id) across a batch of signals before a bulk schedule change.

verification:
  status: verified
  tested_at: "2026-09-21"
  product_version: "clay CLI 1.2.0"
  command: "clay signals update td_0tlqav4Ecpo5M6tsbV9 --schedule weekly"
  expected_result: "schedule.periodUnit changes to 'weekly' in the response, while filter and targeting (segmentIds, entityType) remain exactly as they were before the update."