# client.schedules

> client.schedules — the schedules operations.

`client.schedules` — the `schedules` operations.

On `AsyncKindgi` every method is the same, awaited.

## `client.schedules.list()`

```python signature
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
```

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()`

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

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()`

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

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

## `client.schedules.update()`

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

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()`

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

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()`

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

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()`

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

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()`

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

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()`

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

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()`

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

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.