client.schedules

client.schedules — the schedules operations.

On AsyncKindgi every method is the same, awaited.

client.schedules.list()

list(
    *,
    limit: int | None = None,
    cursor: str | None = None,
    status: Literal['active', 'paused'] | None = None,
    project_id: str | UUID | None = None,
    timeout: float | None = None,
) -> ScheduleCollectionPage

Signature

List cron schedules. GET /v1/schedules

Cursor-paginated. Tombstoned rows excluded. Optional ?status=active|paused and ?projectId= (one project's schedules) filters. Each schedule's owner.displayName is the owner's name now (the person's or the service account's), when it can be read.

client.schedules.register()

register(
    body: RegisterScheduleBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ScheduleRecord

Signature

Register a cron schedule. POST /v1/schedules

Registers a kind=cron trigger. nextFireAt is precomputed from the cron expression at register time; the cron scheduler in the runtime fires due triggers. Malformed cron expressions return 400 trigger-invalid-config without registering.

client.schedules.get()

get(
    trigger_id: str | UUID,
    /,
    *,
    upcoming: int | None = None,
    timeout: float | None = None,
) -> ScheduleRecord

Signature

Fetch a cron schedule. GET /v1/schedules/{triggerId}

client.schedules.update()

update(
    trigger_id: str | UUID,
    body: PatchScheduleBody | Mapping[str, Any] | None = None,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
    **fields: Any,
) -> ScheduleRecord

Signature

Update a cron schedule. PATCH /v1/schedules/{triggerId}

Partial merge on config. If config.cronExpression changes, nextFireAt is recomputed. label: null clears the label; omit to leave unchanged. Malformed cron expressions return 400 trigger-invalid-config.

client.schedules.pause()

pause(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ScheduleRecord

Signature

Pause a cron schedule. POST /v1/schedules/{triggerId}/pause

Idempotent-per-state: pausing an already-paused row returns 409 trigger-already-in-state.

client.schedules.resume()

resume(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ScheduleRecord

Signature

Resume a cron schedule. POST /v1/schedules/{triggerId}/resume

Recomputes nextFireAt so the scheduler picks up the resumed row on its next tick.

client.schedules.unregister()

unregister(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ScheduleUnregisterResult

Signature

Soft-delete a cron schedule (tombstone). POST /v1/schedules/{triggerId}/unregister

Tombstones the schedule; the cron scheduler ignores tombstoned triggers. Retention may hard-remove tombstoned triggers after the tombstone window.

client.schedules.fires()

fires(
    trigger_id: str | UUID,
    /,
    *,
    limit: int | None = None,
    cursor: str | None = None,
    timeout: float | None = None,
) -> ScheduleFirePage

Signature

A schedule's fire history. GET /v1/schedules/{triggerId}/fires

Newest first: each occurrence (and run-now) the schedule fired for, and what came of it: the run it started, or why it was skipped, refused or failed.

client.schedules.run_now()

run_now(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ScheduleFire

Signature

Run a schedule now. POST /v1/schedules/{triggerId}/run-now

One fire outside the schedule (manual: true in its history), starting one run as the schedule's owner. The schedule's next occurrence is unchanged.

client.schedules.take_ownership()

take_ownership(
    trigger_id: str | UUID,
    /,
    *,
    idempotency_key: str | None = None,
    timeout: float | None = None,
) -> ScheduleRecord

Signature

Take over a schedule. POST /v1/schedules/{triggerId}/owner

The caller becomes the schedule's owner, so its runs act as the caller from the next fire. Needs admin on the schedule's project and execute on what it runs. For a schedule whose owner left or lost access.