> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# schedule()

> `protected` **schedule**(`delaySeconds`, `method`, `payload?`, `opts?`): `Promise`\<`string`>

Schedule a persistent task to run once, `delaySeconds` from now.

A task names a method on your class: when the timer fires, the SDK calls
`this[method](payload)` — one argument, the payload. If no such method
exists, [`onTask`](/docs/agent-sdk/interface/onTask) fires instead. Tasks are persistent:
they survive crashes and restarts, riding the actor's single alarm slot.

Delivery is at-least-once — write handlers to be idempotent. A task that
throws is retried with exponential backoff (starting around a second,
capped at 5 minutes) up to `opts.maxRetries` times after the first
delivery (default 5), then parked (dropped without firing again).

With a stable `opts.id`, scheduling is an upsert — the prior task with
that id is replaced and the timer re-armed. Payloads must be
storage-codec-safe or a `CodecError` is thrown.

A task handler may schedule and cancel tasks, its own id included — the
usual shape for a poller that books its next look, or a task that stops
itself. What the handler leaves behind stands: the run that is finishing
never removes or overwrites it. Retry accounting still applies, though, so
a handler that re-schedules its own task and then throws keeps the task it
wrote but not a clean slate — the failure counts toward `maxRetries`, and
the task fires no sooner than the backoff. (A handler that *cancels* its
own task and then throws stays cancelled.)

**Parameters**

| Parameter | Type | Description |
| - | - | - |
| `delaySeconds` | `number` | Delay before the task fires, in **seconds**. |
| `method` | `string` | Name of the method to invoke when the task fires. |
| `payload?` | `unknown` | Value passed to the method; stored persistently with the task. |
| `opts?` | [`ScheduleOptions`](/docs/agent-sdk/interface/schedule#scheduleoptions) | Stable id and retry policy — see [ScheduleOptions](/docs/agent-sdk/interface/schedule#scheduleoptions). |

**Returns**

`Promise`\<`string`>

The task id (pass to
[`cancelSchedule`](/docs/agent-sdk/interface/cancelSchedule)).

## ScheduleOptions

Options for schedule()/queue()/every().

**Properties**

**everyMs?**

> `optional` **everyMs?**: `number`

Recurrence interval in ms. Set by every(); re-inserts the next fire.

***

**id?**

> `optional` **id?**: `string`

Stable id. Re-scheduling with the same id replaces the prior task
(dedup + re-arm). Omit for a random id. Must not contain a codec-unsafe
value; keep it a plain string.

***

**maxRetries?**

> `optional` **maxRetries?**: `number`

Retries AFTER the first delivery before the task is parked (dropped).
Default 5, so a task runs up to `maxRetries + 1` times total.