Scheduled Jobs

toothfairyai@latest…

Manager for scheduled jobs (cron jobs) operations.

This manager provides methods to create, update, and manage scheduled jobs.

Example:

>>> client = ToothFairyClient(api_key="...", workspace_id="...")
>>> scheduled_job = client.scheduled_jobs.create(
...     name="Daily Report",
...     agent_id="agent-123",
...     schedule={"frequency": "DAILY", "hour": 9, "minute": 0},
...     timezone="UTC",
... )

Accessed via client.scheduledJobs.

Methods

Method	HTTP	Endpoint
`create`	POST	`POST /scheduled_job/create`
`update`	POST	`POST /scheduled_job/update`
`delete`	DELETE	`DELETE /scheduled_job/delete/{scheduled_job_id}`
`get`	GET	`GET /scheduled_job/get/{scheduled_job_id}`
`list`	GET	`GET /scheduled_job/list`
`get_active`	—	derived
`get_by_status`	—	derived
`get_by_agent`	—	derived
`pause`	—	derived
`resume`	—	derived
`search`	—	derived

create

Create a new scheduled job.

def create(
    name: str,
    agent_id: str,
    custom_prompt_id: str,
    timezone: str = 'UTC',
    description: Optional[str] = None,
    forced_prompt: Optional[str] = None,
    schedule: Optional[Union[CronSchedule, Dict[str, Any]]] = None,
    frequency: CronJobFrequency = 'DAILY',
    interval: Optional[int] = None,
    cron_expression: Optional[str] = None,
    day_of_week: Optional[int] = None,
    day_of_month: Optional[int] = None,
    hour: Optional[int] = None,
    minute: Optional[int] = None,
    is_active: bool = True,
    start_date: Optional[str] = None,
    end_date: Optional[str] = None,
    status: Optional[CronJobStatusRequest] = None,
    execution_config: Optional[Union[CronExecutionConfig, Dict[str, Any]]] = None,
    notification_config: Optional[Union[CronNotificationConfig, Dict[str, Any]]] = None,
    retry_config: Optional[Union[CronRetryConfig, Dict[str, Any]]] = None,
    metadata: Optional[Dict[str, Any]] = None,
    cron_type: Optional[str] = None,
    routine_config: Optional[Union[Dict[str, Any], Any]] = None
) -> ScheduledJob

Endpoint: POST /scheduled_job/create · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
`id`	`id`	`string`	no	Unique identifier
`workspace_id`	`workspaceid`	`string`	yes	Unique workspace identifier (UUID v4)
`name`	`name`	`string`	yes	Name of the resource
`description`	`description`	`string`	no	Detailed description of purpose and capabilities
`forced_prompt`	`forcedPrompt`	`string`	no	Forced prompt text to use for the job (max 1024 chars)
`agent_id`	`agentID`	`string`	yes	ID of the agent associated with this resource
`type`	`type`	`string`	no	Type classification (free-form string identifier)
`routine_config`	`routineConfig`	`string`	no	Configuration for routine jobs (maxPlannedActions)
`custom_prompt_id`	`customPromptID`	`string`	no	ID of a custom prompt to use
`schedule`	`schedule`	`string`	no	Schedule configuration object (frequency, interval, cronExpression, etc.)
`timezone`	`timezone`	`string`	no	Timezone for the schedule (e.g. UTC, America/New_York)
`is_active`	`isActive`	`boolean`	no	Whether the job is currently active
`status`	`status`	`string`	no	Current status of the resource

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response fields

Field	Type	Description
`id`	`string`	Unique identifier for the scheduled job
`name`	`string`	Name of the resource
`description`	`string`	Detailed description of purpose and capabilities
`forcedPrompt`	`string`	Forced prompt override
`type`	`string`	Type classification (free-form string identifier)

Example

client.scheduledJobs.create(name="…", agent_id="agent-id", custom_prompt_id="agent-id")

update

Update a scheduled_job.

def update(scheduled_job_id: str) -> ScheduledJob

Endpoint: POST /scheduled_job/update · API service

Request fields

Python kwarg	Wire field	Type	Required	Description
`id`	`id`	`string`	yes	Unique identifier
`workspace_id`	`workspaceid`	`string`	no	Unique workspace identifier (UUID v4)
`name`	`name`	`string`	no	Name of the resource
`description`	`description`	`string`	no	Detailed description of purpose and capabilities
`forced_prompt`	`forcedPrompt`	`string`	no	Forced prompt text to use for the job (max 1024 chars)
`agent_id`	`agentID`	`string`	no	ID of the agent associated with this resource
`type`	`type`	`string`	no	Type classification (free-form string identifier)
`routine_config`	`routineConfig`	`string`	no	Configuration for routine jobs (maxPlannedActions)
`custom_prompt_id`	`customPromptID`	`string`	no	ID of a custom prompt to use
`schedule`	`schedule`	`string`	no	Schedule configuration object (frequency, interval, cronExpression, etc.)
`timezone`	`timezone`	`string`	no	Timezone for the schedule (e.g. UTC, America/New_York)
`is_active`	`isActive`	`boolean`	no	Whether the job is currently active
`status`	`status`	`string`	no	Current status of the resource

Always pass snake_case keyword arguments — the Python kwarg column shows the exact name to use for each wire field (as a named parameter where it appears in the method signature, otherwise via **kwargs). The SDK converts it deterministically to the camelCase wire key the API expects. Passing camelCase directly is deprecated: it emits a warning and converts to the same wire key.

Response

Returns the ScheduledJob object — fields documented in the create section above.

Example

client.scheduledJobs.update(scheduled_job_id="agent-id")

delete

Delete a scheduled_job.

def delete(scheduled_job_id: str) -> Dict[str, bool]

Endpoint: DELETE /scheduled_job/delete/{scheduled_job_id} · API service

Example

client.scheduledJobs.delete(scheduled_job_id="agent-id")

get

Get a scheduled_job by ID.

def get(scheduled_job_id: str) -> ScheduledJob

Endpoint: GET /scheduled_job/get/{scheduled_job_id} · API service

Response

Returns the ScheduledJob object — fields documented in the create section above.

Example

client.scheduledJobs.get(scheduled_job_id="agent-id")

list

List all scheduled jobs.

def list(
    limit: Optional[int] = None,
    offset: Optional[int] = None
) -> ListResponse

Endpoint: GET /scheduled_job/list · API service

Example

client.scheduledJobs.list()